/ 
Mojolicious-Plugin-Hakkefuin-0.1.3
/ Mojolicious::Plugin::Hakkefuin

NAME

Mojolicious::Plugin::Hakkefuin - Mojolicious Web Authentication.

SYNOPSIS

Mojolicious::Lite example (SQLite default):

use Mojolicious::Lite;

plugin 'Hakkefuin' => {
  'helper.prefix' => 'fuin',
  'stash.prefix'  => 'fuin',
  via             => 'sqlite',        # or mariadb / pg
  dir             => 'migrations',
  'c.time'        => '1w',            # auth cookie TTL
  's.time'        => '1w',            # session TTL
  'lock'          => 1,               # enable lock/unlock helpers
};

post '/login' => sub {
  my $c   = shift;
  my $id  = $c->param('user');
  my $res = $c->fuin_signin($id);
  return $c->render(status => $res->{code}, json => $res);
};

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

under sub {
  my $c    = shift;
  my $auth = $c->fuin_has_auth;         # checks cookie+csrf, stashes data
  return $c->render(status => 423, json => $auth) if $auth->{result} == 2;
  return $c->render(status => 401, text => 'Unauthorized')
    unless $auth->{result} == 1;
  $c->fuin_csrf;                        # ensure CSRF is in session/headers
  return 1;
};

get '/me' => sub {
  my $c = shift;
  $c->render(json => {user => $c->stash('fuin.identify')});
};

# Rotate auth with custom TTLs without re-login
get '/auth-update-custom' => sub {
  my $c   = shift;
  my $bid = $c->stash('fuin.backend-id');
  my $res = $c->fuin_auth_update($bid, {c_time => '45m', s_time => '20m'});
  $c->render(status => $res->{code}, json => $res);
};

post '/logout' => sub {
  my $c   = shift;
  my $res = $c->fuin_signout($c->stash('fuin.identify'));
  $c->render(status => $res->{code}, json => $res);
};

app->start;

Mojolicious (non-Lite) menambahkan plugin di dalam startup:

sub startup {
  my $self = shift;
  $self->plugin(Hakkefuin => { via => 'pg', dir => 'migrations/pg' });
  ...
}

DESCRIPTION

Mojolicious::Plugin::Hakkefuin is a Mojolicious plugin for Web Authentication. (Minimalistic and Powerful).

OPTIONS

helper.prefix

# Mojolicious
$self->plugin('Hakkefuin' => {
  'helper.prefix' => 'your_prefix_here'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'helper.prefix' => 'your_prefix_here'
};

To change prefix of all helpers. By default, helper.prefix is mhf.

stash.prefix

# Mojolicious
$self->plugin('Hakkefuin' => {
  'stash.prefix' => 'your_stash_prefix_here'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'stash.prefix' => 'your_stash_prefix_here'
};

To change prefix of stash. By default, stash.prefix is mhf.

csrf.name

# Mojolicious
$self->plugin('Hakkefuin' => {
  'csrf.name' => 'your_csrf_name_here'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'csrf.name' => 'your_csrf_name_here'
};

To change csrf name in session and HTTP Headers. By default, csrf.name is mhf_csrf_token.

via

# Mojolicious
$self->plugin('Hakkefuin' => {
  via => 'mariadb', # OR
  via => 'pg'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  via => 'mariadb', # OR
  via => 'pg'
};

Use one of 'mariadb' or 'pg' or 'sqlite'. (For 'sqlite' option does not need to be specified, as it would by default be using 'sqlite' if option via is not specified).

dir

# Mojolicious
$self->plugin('Hakkefuin' => {
  dir => 'your-custom-dirname-here'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  dir => 'your-custom-dirname-here'
};

Specified directory for Mojolicious::Plugin::Hakkefuin configure files.

c.time

# Mojolicious
$self->plugin('Hakkefuin' => {
  'c.time' => '1w'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'c.time' => '1w'
};

To set a cookie expires time. By default is 1 week.

s.time

# Mojolicious
$self->plugin('Hakkefuin' => {
  's.time' => '1w'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  's.time' => '1w'
};

To set a cookie session expires time. By default is 1 week. For more information of the abbreviation for time c.time and s.time helper, see Mojo::Hakkefuin::Utils.

lock

# Mojolicious
$self->plugin('Hakkefuin' => {
  'lock' => 1
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'lock' => 1
};

To set Lock Screen feature. By default is 1 (enable). If you won't use that feature, you can give 0 (disable). This feature is additional authentication method, beside login and logout. When enabled a dedicated lock cookie is issued and tracked in the backend.

cl.time

# Mojolicious
$self->plugin('Hakkefuin' => {
  'cl.time' => '60m'
});

# Mojolicious Lite
plugin 'Hakkefuin' => {
  'cl.time' => '60m'
};

To set cookie lock expires time. By default is 60 minutes for the lock cookie used by mhf_lock/mhf_unlock.

HELPERS

By default, prefix for all helpers using mhf, but you can do change that with option helper.prefix.

mhf_lock

$c->mhf_lock() # In the controllers

Helper to lock the current authenticated session; sets lock cookie and marks backend as locked.

mhf_unlock

$c->mhf_unlock(); # In the controllers

Helper to unlock a locked session; clears lock cookie and unlocks backend.

mhf_signin

$c->mhf_signin('login-identify') # In the controllers

Helper for action sign-in (login) web application.

mhf_signout

$c->mhf_signout('login-identify'); # In the controllers

Helper for action sign-out (logout) web application.

mhf_auth_update

$c->mhf_auth_update('login-identify'); # In the controllers

Helper for rotating authentication cookie and CSRF token.

mhf_has_auth

$c->mhf_has_auth; # In the controllers

Helper for checking if routes has authenticated.

mhf_csrf

$c->mhf_csrf; # In the controllers
<%= mhf_csrf %> # In the template.

Helper for generate csrf;

mhf_csrf_val

$c->mhf_csrf_val; # In the controllers

Helper for comparing stored CSRF (session/header) and returning it when it matches.

mhf_csrf_get

$c->mhf_csrf_get; # In the controllers

Helper for retrieving the stored CSRF token.

mhf_csrf_regen

$c->mhf_csrf_regen; # In the controllers

Helper for regenerating CSRF token and returning the new value.

mhf_backend

$c->mhf_backend; # In the controllers

Helper for access to backend.

METHODS

Mojolicious::Plugin::Hakkefuin inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

$plugin->register(Mojolicious->new);

Register plugin in Mojolicious application.

SEE ALSO

https://github.com/CellBIS/mojo-hakkefuin, <Mojolicious::Guides>, https://mojolicious.org.

AUTHOR

Achmad Yusri Afandi, yusrideb@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2025 by Achmad Yusri Afandi

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.