view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# Concierge::Auth

Concierge authorization framework - production-ready authentication and authorization with substitutable backends.

## VERSION

v0.5.2

## DESCRIPTION

Concierge::Auth provides comprehensive user authentication and authorization capabilities through a substitutable backend architecture — any backend implementing the same contract (LDAP, OAuth, etc.) can be swapped in. Token generation is available...

## FEATURES

- **Substitutable Backends**: swap in any backend implementing the
  `Concierge::Auth::Base` contract (LDAP, OAuth, etc.)
- **Token Generation**: Generate cryptographically secure tokens and UUIDs
- **Generator Architecture**: Extensible generator system for tokens and identifiers
- **Built-in Backend**: a password-file backend (`Concierge::Auth::Pwd`)
  ships with this distribution — see "Built-in Authentication" below

## MODULE STRUCTURE

- **Concierge::Auth** - Backend factory / facade
- **Concierge::Auth::Base** - Backend contract that all backends implement
- **Concierge::Auth::Pwd** - Built-in password-file backend
- **Concierge::Auth::Generators** - Token and identifier generation system

## INSTALLATION

From source:
```bash
perl Makefile.PL
make
make test
make install
```

From CPAN:
```bash
cpanm Concierge::Auth
```

## QUICK START

```perl
use Concierge::Auth;

my $auth = Concierge::Auth->new(
    backend_class => 'Concierge::Auth::Pwd',
    file          => '/path/to/users.passwd',
);

my $result = $auth->enroll($user_id, $password);
my $result = $auth->authenticate($user_id, $password);
my $result = $auth->is_id_known($user_id);
my $result = $auth->change_credentials($user_id, $new_password);
my $result = $auth->revoke($user_id);

# Generators -- work with or without a file
# (backend_class => 'Concierge::Auth::Pwd', no_file => 1)
my $token = $auth->gen_random_token();
my $uuid  = $auth->gen_uuid();
```

Each of the five core methods above returns a hashref: `{ success => 1, ... }`
on success, or `{ success => 0, message => '...' }` on failure. See
`Concierge::Auth::Base` for the full contract.

## Built-in Authentication (Concierge::Auth::Pwd)

`Concierge::Auth::Pwd` is the password-file backend bundled with this
distribution — the `backend_class` used in the example above.

- **Password Management**: Argon2 encoder (via Crypt::Passphrase) with a
  Bcrypt fallback validator for legacy password verification
- **File-based Authentication**: encrypted passwords stored in a plain
  password file, never in plaintext
- **File Locking**: proper `flock()` support for concurrent access
- **Password Utilities**: password strength validation, on top of the
  random string/token generators shared with all backends
- **Flexible**: works with or without a password file (`no_file => 1`)
  when only the generator methods are needed

Password security defaults:
- Primary encoder: Argon2 (memory-hard, resistant to GPU/ASIC attacks)
- Fallback validator: Bcrypt (for backward compatibility)
- Password length: 8-72 characters (bcrypt limit)
- User ID validation: 2-32 characters, alphanumeric plus `. _ @ -`

See `perldoc Concierge::Auth::Pwd` for the full backend documentation.

The generator methods (`gen_random_token`, `gen_uuid`, etc.) are different:
they follow a `wantarray` `(value)` / `(value, message)` dual-return
convention rather than returning a hashref, so context matters:

```perl
my ($token, $msg) = $auth->gen_random_token();  # list context
my $token          = $auth->gen_random_token();  # scalar context: $msg discarded
```

## REQUIREMENTS

- Perl 5.36 or higher
- Carp
- Fcntl
- Crypt::Passphrase
- Crypt::PRNG
- parent
- Exporter
- Test2::V0 (for testing)

## PRODUCTION USE

Concierge::Auth is actively used in production environments. Key features for production:

- **Error Handling**: Comprehensive error checking and reporting