NAME

Concierge - Service layer orchestrator for authentication, sessions, and user data

VERSION

v0.8.0

SYNOPSIS

use Concierge;

# Open an existing desk (created by Concierge::Desk::Setup)
my $desk = Concierge->open_desk('./desk');
my $concierge = $desk->{concierge};

# Register a user
$concierge->add_user({
    user_id  => 'alice',
    moniker  => 'Alice',
    email    => 'alice@example.com',
    password => 'secret123',
});

# Log in -- returns a Concierge::Desk::User object
my $login = $concierge->login_user({
    user_id  => 'alice',
    password => 'secret123',
});
my $user = $login->{user};

# User object provides direct access
say $user->moniker;         # "Alice"
say $user->session_id;      # random hex string
say $user->is_logged_in;    # 1

# Restore user from a cookie on next request
my $restore = $concierge->restore_user($user->user_key);
my $same_user = $restore->{user};

# Log out
$concierge->logout_user($user->session_id);

DESCRIPTION

Concierge coordinates three component modules behind a single API:

Concierge::Auth -- password authentication (Argon2)
Concierge::Sessions -- session management (SQLite or file backends)
Concierge::Users -- user data storage (SQLite, YAML, or CSV/TSV backends)

Applications interact only with Concierge and the Concierge::Desk::User objects it returns. The component modules are never exposed directly.

What the Suite Provides

Concierge handles orchestration -- coordinating components, managing the user_key mapping, and returning consistent structured results. The capabilities of the suite live in the three components:

Authentication (Concierge::Auth): Argon2id password hashing and verification; no plaintext credentials are ever written to disk. Also provides random token, UUID, word-passphrase, and hex-ID generators. The component is substitutable: any replacement implementing the same method contract (checkPwd, setPwd, resetPwd, etc.) can replace it for LDAP, OAuth, or any other scheme.

Sessions (Concierge::Sessions): Full session lifecycle -- creation, retrieval, expiry, and cleanup -- with SQLite, file, or in-memory backends. Sessions carry arbitrary key/value data. A single-session-per-user policy is enforced: creating a new session automatically removes any prior session for that user. Expired sessions are cleaned up each time a desk is opened.

User Records (Concierge::Users): User data store with a configurable field schema. Standard fields (moniker, email, phone, access_level, user_status, term_ends, and others) are built in and can be selectively overridden. Applications add their own fields via app_fields at setup time. Supports SQLite, YAML, and CSV/TSV backends, with filtering and listing operations.

For the full API of any component, see its own documentation.

Desks

A desk is a storage directory containing the configuration and data files for all three components. Use Concierge::Desk::Setup to create a desk, then open_desk() to load it at runtime.

User Participation Levels

Concierge provides three graduated levels of user participation, each returning a Concierge::Desk::User object:

Visitor -- admit_visitor(): Assigned a unique identifier only. No session, no stored data. Suitable for anonymous tracking (e.g., cookies).
Guest -- checkin_guest(): Assigned an identifier and a session. Can store temporary data (e.g., a shopping cart). No authentication or persistent user record.
Logged-in user -- login_user(): Authenticated with credentials. Has a session, persistent user data, and full access to the User object's data methods.

A guest can be converted to a logged-in user with login_guest(), transferring any session data accumulated during the guest session.

User Keys

Each active user (guest or logged-in) is tracked by a user_key -- a random token stored in the concierge's user_keys mapping alongside the user's user_id and session_id. This mapping is persisted to user_keys.json in the desk directory and synchronized against active sessions when the desk is opened.

Return Values

All methods return a hashref with at least success (0 or 1) and message:

# Success
{ success => 1, message => '...', ... }

# Failure
{ success => 0, message => 'error description' }

Success responses include additional fields relevant to the operation:

User lifecycle methods (login_user(), restore_user(), checkin_guest(), admit_visitor(), login_guest()) return user, a Concierge::Desk::User object. Guest and visitor results also set is_guest or is_visitor to 1.
open_desk() returns concierge, the ready-to-use Concierge object.
User management methods return user_id. remove_user() also returns deleted_from (arrayref of component names) and, if any deletion failed, warnings (arrayref).
verify_user() returns verified (0 or 1), exists_in_auth, and exists_in_users.
list_users() returns user_ids (arrayref) and count. With include_data => 1, also returns users (hashref keyed by user_id).

See the individual method descriptions below for the complete field list.

Methods never croak during normal operation. The one exception is open_desk(), which croaks if the desk directory does not exist.

Architecture

Concierge ships with three identity core components:

Concierge::Auth -- credential storage and verification
Concierge::Sessions -- session lifecycle and persistence
Concierge::Users -- user records with configurable field schemas

These three are tightly orchestrated: a single login_user() call authenticates via Auth, retrieves a record from Users, and creates a session through Sessions. This coordination is the purpose of Concierge -- applications interact with the Concierge API and the Concierge::Desk::User objects it returns, not with the components directly.

The identity core is designed to be sufficient on its own, but the component pattern it follows -- backend abstraction, setup-time configuration, and Concierge-level orchestration -- is intentionally replicable. Each identity core component can also be substituted with a conforming replacement, and additional components (Organizations, Assets, etc.) can be added by following the same conventions. See "EXTENSIBILITY" for details.

METHODS

Desk Management

open_desk

my $result = Concierge->open_desk($desk_location);
my $concierge = $result->{concierge};

Opens an existing desk directory created by Concierge::Desk::Setup. Reads the configuration file, instantiates all component modules, loads the user_keys mapping, and runs session cleanup.

Croaks if $desk_location is not an existing directory.

Returns { success => 1, concierge => $obj } on success.

User Lifecycle

admit_visitor

my $result = $concierge->admit_visitor();
my $user = $result->{user};    # Concierge::Desk::User (visitor)

Creates a visitor with a generated identifier. No session is created and no data is stored.

checkin_guest

my $result = $concierge->checkin_guest(\%session_opts);
my $user = $result->{user};    # Concierge::Desk::User (guest)

Creates a guest with a generated identifier and a session. The optional %session_opts hashref may include timeout (in seconds; defaults to 1800).

login_user

my $result = $concierge->login_user(\%credentials, \%session_opts);
my $user = $result->{user};    # Concierge::Desk::User (logged-in)

Authenticates user_id and password from %credentials, retrieves the user's data record, creates a session, and returns a fully-equipped User object. If the user already has an active session, the previous session is replaced.

restore_user

my $result = $concierge->restore_user($user_key);
my $user = $result->{user};    # Concierge::Desk::User (guest or logged-in)

Reconstructs a User object from a user_key (typically stored in a cookie or URL token). Looks up the key in the concierge mapping, validates the session, and determines whether the user is a guest or logged-in user.

Logged-in users are restored with their full user data snapshot and backend closures. Guests are restored with their session only.

If the session has expired, the stale mapping entry is cleaned up and the method returns failure. The application can then redirect to login or create a new guest as appropriate.

Returns { success => 1, user => $user } on success. Guest restores also include is_guest => 1.

login_guest

my $result = $concierge->login_guest(\%credentials, $guest_user_key);
my $user = $result->{user};    # Concierge::Desk::User (logged-in)

Converts a guest to a logged-in user. Authenticates with %credentials, transfers any data from the guest's session to the new session, then deletes the guest session and removes the guest's user_key mapping.

logout_user

my $result = $concierge->logout_user($session_id);

Deletes the session and removes the user_key mapping entry.

Admin Operations

add_user

my $result = $concierge->add_user(\%user_input);

Registers a new user. %user_input must include user_id, moniker, and password. Any additional fields (email, phone, application- defined fields, etc.) are stored in the Users component. The password is stored separately in the Auth component and never reaches the user data store.

If password validation fails, the Users record is rolled back.

remove_user

my $result = $concierge->remove_user($user_id);

Removes the user from all components: Users, Auth, Sessions, and the user_keys mapping. Attempts all deletions; the response includes deleted_from (arrayref) and warnings (arrayref, if any component deletion failed).

verify_user

my $result = $concierge->verify_user($user_id);

Checks whether $user_id exists in both Auth and Users components. Returns verified => 1 only if present in both. Includes exists_in_auth and exists_in_users flags, and a warning if the user exists in one component but not the other.

list_users

# IDs only
my $result = $concierge->list_users($filter, \%options);
my @ids = @{ $result->{user_ids} };

# With full data
my $result = $concierge->list_users('', { include_data => 1 });
my %users = %{ $result->{users} };

Returns user IDs from the Users component. $filter is a string passed through to Concierge::Users. With include_data => 1, fetches each user's full record into a users hash keyed by user_id. With fields => [...], returns only the specified fields per user.

get_user_data

my $result = $concierge->get_user_data($user_id, @fields);
my $data = $result->{user};

Retrieves user data from the Users component. If @fields is provided, returns only those fields; otherwise returns all fields.

update_user_data

my $result = $concierge->update_user_data($user_id, \%updates);

Updates the user's record in the Users component. The user_id and password fields are filtered out and cannot be changed through this method.

Password Operations

Initial password registration is handled by add_user(), which sets the password atomically with user creation. The methods here operate on passwords for existing users.

verify_password

my $result = $concierge->verify_password($user_id, $password);

Checks whether $password is correct for $user_id. Returns success => 1 if the password matches.

reset_password

my $result = $concierge->reset_password($user_id, $new_password);

Sets a new password for an existing user. The application is responsible for verifying the user's identity before calling this method.

PARAMETER FILTERS

Concierge uses Params::Filter to enforce data segregation at method boundaries:

$auth_data_filter -- extracts only user_id and password
$user_data_filter -- extracts everything except password
$session_data_filter -- extracts user_id plus non-credential fields
$user_update_filter -- excludes user_id and password from updates

These ensure that credentials never leak into user data stores and that identity fields cannot be changed via update operations.

EXTENSIBILITY

Component Substitution

Each identity core component can be replaced with a drop-in alternative as long as the replacement implements the methods Concierge calls on it.

Auth -- Concierge calls:

Concierge::Auth->new(\%args) -- constructor; accepts file key
$auth->checkID($user_id) -- returns true/false
$auth->checkPwd($user_id, $password) -- returns ($ok, $message)
$auth->setPwd($user_id, $password) -- returns ($ok, $message)
$auth->resetPwd($user_id, $new_password) -- returns ($ok, $message)
$auth->deleteID($user_id) -- returns ($ok, $message)
Concierge::Auth->gen_random_string($length) -- class method, returns string

Sessions -- Concierge calls:

Concierge::Sessions->new(%args) -- constructor; accepts storage_dir and backend
$sessions->new_session(%args) -- returns { success => 1, session => $obj }
$sessions->get_session($session_id) -- returns { success => 1, session => $obj }
$sessions->delete_session($session_id) -- returns { success => 1|0, ... }
$sessions->cleanup_sessions() -- returns { success => 1, deleted_count => N, active => [...] }

Users -- Concierge calls:

Concierge::Users->new($config_file) -- constructor
$users->register_user(\%data) -- returns { success => 1|0, message => '...' }
$users->get_user($user_id) -- returns { success => 1, user => \%data }
$users->update_user($user_id, \%updates) -- returns { success => 1|0, ... }
$users->delete_user($user_id) -- returns { success => 1|0, ... }
$users->list_users($filter) -- returns { success => 1, user_ids => [...] }

To substitute a component, supply an object that responds to these methods and assign it to the corresponding slot on the concierge object after open_desk():

my $result = Concierge->open_desk($desk_dir);
my $c = $result->{concierge};
$c->{auth} = My::LDAPAuth->new(...);   # drop-in replacement

Additional Components

To add a new records-store component (Organizations, Assets, Catalog, etc.):

Subclass Concierge::Desk::Base and implement its seven stub methods. Concierge::Desk::Base documents the method signatures and the { success = 1|0, message => '...' }> return convention.

Add a configuration block for your component in concierge.conf:

{ "organizations_config": { "backend": "sqlite", "db_file": "..." } }

After open_desk(), instantiate and attach the component:

my $result = Concierge->open_desk($desk_dir);
my $c = $result->{concierge};
my $orgs = Concierge::Organizations->new();
$orgs->setup($desk_config->{organizations_config});
$c->{organizations} = $orgs;

Access the component through the concierge object:

my $r = $c->{organizations}->add_record('acme', \%data);

Future Components

The following illustrate the kinds of components the Concierge:: namespace is suited for. These are not roadmap commitments -- they are examples of what the component pattern enables:

Concierge::Organizations -- multi-tenancy; users belong to orgs
Concierge::Assets -- files, images, or other owned resources
Concierge::Guides -- role and permission records
Concierge::Catalog -- product or content records
Concierge::Calendar -- event and booking records

Contributing

If you build a component that might be useful to others, contributions to the Concierge:: namespace on CPAN are welcome. The conventions to follow are: subclass Concierge::Desk::Base, use the { success = 1|0, message => '...' }> return convention, accept a desk config block via setup(), and include comprehensive tests and POD. Open an issue or pull request at https://github.com/bwva/Concierge to discuss before publishing.

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

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

To install Concierge, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Concierge

CPAN shell

perl -MCPAN -e shell
install Concierge

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)