view release on metacpan or  search on metacpan

examples/README.md  view on Meta::CPAN

# Token-based API
my $auth = Concierge::Auth->new({no_file => 1});

# Generate API keys
sub generate_api_key {
    my ($user_id, $permissions) = @_;
    return $auth->gen_random_token(32, 'url_safe');
}
```

## Best Practices

### Security
- Store auth files outside web-accessible directories
- Use HTTPS for all authentication endpoints
- Implement proper session management
- Log security events for monitoring
- Regular password policy updates

### Error Handling
- Validate inputs before processing
- Use consistent error messages
- Don't expose internal errors to users
- Implement proper logging
- Handle edge cases gracefully

### Performance
- Cache authentication results appropriately
- Use efficient file operations
- Consider database backends for large scale
- Monitor authentication performance
- Implement reasonable timeouts

## Testing Your Integration

```bash
# Test basic functionality
perl -MConcierge::Auth -e '
    my $auth = Concierge::Auth->new({file => "/tmp/test.db"});
    my ($s, $m) = $auth->setPwd("test", "password123");
    print $s ? "✓ Registration works\n" : "✗ Registration failed: $m\n";
    my $ok = $auth->checkPwd("test", "password123");
    print $ok ? "✓ Authentication works\n" : "✗ Authentication failed\n";
'

# Test token generation
perl -MConcierge::Auth -e '
    my $auth = Concierge::Auth->new({no_file => 1});
    print "Session token: " . $auth->gen_random_token(24) . "\n";
    print "API key: " . $auth->gen_random_token(32, "alphanumeric") . "\n";
    print "UUID: " . $auth->gen_uuid() . "\n";
'
```

## Common Patterns

### User Registration Flow
1. Validate input format
2. Check if user already exists
3. Hash password securely
4. Store user credentials
5. Return success/failure

### Authentication Flow
1. Validate input format
2. Look up user credentials
3. Verify password against hash
4. Generate session token on success
5. Return authentication result

### Session Management
1. Generate secure session token
2. Store session metadata
3. Validate token on each request
4. Update last active timestamp
5. Handle session expiration

## Security Considerations

- **Password Security**: Uses Argon2 for new passwords, bcrypt compatibility
- **File Security**: Restrictive permissions (0600), atomic operations
- **Token Security**: Cryptographically secure random generation
- **Input Validation**: Comprehensive validation with clear error messages
- **Concurrent Access**: File locking prevents corruption

## See Also

- [Concierge::Auth POD Documentation](../Auth.pm)
- [Test Suite](../tests/Auth/)
- [CPAN Page](https://metacpan.org/pod/Concierge::Auth) (when published)

## Support

For questions, bug reports, or feature requests, please contact the maintainer or create an issue in the project repository.