=head1 NAME

Mozilla::Persona::Server - persona user validation

=head1 SYNOPSIS

  # run set-up script first
  persona setup <options>

  my $persona = Mozilla::Persona->new(...);
  my $persona = Mozilla::Persona->fromConfig($fn);
  $persona->writeConfig($fn);

=head1 DESCRIPTION

This module organizes the server-side Persona adminstration, with
a few helpers which can have alternative implementations.

=head1 METHODS

=head2 Constructors

=over 4

=item Mozilla::Persona::Server-E<gt>B<fromConfig>(FILENAME, OPTIONS)

Read the configuration from FILENAME (which contains JASON).  The OPTIONS
overrule the read data.  The data is used to instantiate this object via
the usual procedure, so see L<new()|Mozilla::Persona::Server/"Constructors">.

=item Mozilla::Persona::Server-E<gt>B<new>(OPTIONS)

 -Option     --Default
  aliases      See manpage Mozilla::Persona::Aliases
  cookie_name  <required>
  domain       <required>
  private_pem  <required>
  validator    See manpage Mozilla::Persona::Validate

=over 2

=item aliases => HASH

One used may have more than one valid email address for various
purposes.  Any of these aliases suffices to login.  The HASH of
information is passed as configuration for the ::Aliases object.

=item cookie_name => STRING

The name of the cookie, used to administer the persona session.

=item domain => DOMAIN

Your domain, which may be a super-level from the website's domain,
or even an other domain you own.

=item private_pem => FILENAME

FILENAME which contains the private key, generated by the set-up
script.

=item validator => HASH

Used to check whether the user is validated for this domain.
The HASH of information is passed as configuration for the
::Aliases object.

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<aliases>()

Returns the aliases object, an L<Mozilla::Persona::Aliases|Mozilla::Persona::Aliases> extension.

The object gets instantiated on first call to this method the first call
to this method, so lazy.

=item $obj-E<gt>B<cookie>()

=item $obj-E<gt>B<domain>()

=item $obj-E<gt>B<privatePEM>()

Returns the Crypt::OpenSSL::RSA object which contains the
private PEM (private key).

=item $obj-E<gt>B<validator>()

Returns the validator object, an L<Mozilla::Persona::Validate|Mozilla::Persona::Validate> extension.

The object gets instantiated on first call to this method the first call
to this method, so lazy.

=back

=head2 Actions

Actions are activities requested by the client.

=over 4

=item $obj-E<gt>B<actionIsLoggedIn>(CGI)

Check whether the user is logged-in.

=item $obj-E<gt>B<actionLogin>(CGI)

Handle a login request.

=item $obj-E<gt>B<actionPing>(CGI)

Used then checking the installation: can the script be run?

=item $obj-E<gt>B<actionSign>(CGI)

Handle a sign request.

=item $obj-E<gt>B<getSession>(CGI)

Return the CGI::Session for this persona user, based of information
received via CGI.

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<isAliasFor>(USER, EMAIL)

Check whether the USER is one of the aliases for the specified EMAIL
address.

=item $obj-E<gt>B<writeConfig>(FILENAME)

Write the configuration of this object to the FILENAME.

=back

=head1 SEE ALSO

This module is part of Mozilla-Persona distribution version 0.12,
built on November 22, 2012. Website: F<http://perl.overmeer.net>.  The code is based on the MulkyID code by
Matthias Benkard.

Persona is described at F<http://www.mozilla.org/persona/>

=head1 COPYRIGHTS

Copyrights of the perl code and the related documentation by
2012 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>