Airlock

 view release on metacpan or  search on metacpan

lib/Airlock.pm  view on Meta::CPAN

  return $self->_fail( $final ? 'too_many_failures' : 'factor_failed', missing => [ $factor->name ] );
}

sub _issue_opaque {
  my ( $self, $grant, $now ) = @_;
  my $token = $self->code->secret;
  $self->store->{insert}->( {
    hash            => $self->code->hash($token),
    kind            => 'token',
    user_code       => undef,
    client_id       => $grant->{client_id},
    scope           => $grant->{scope},
    state           => 'active',
    created         => $now,
    expires         => $now + $self->token_ttl,
    poll_interval   => undef,
    last_poll       => undef,
    subject         => $grant->{subject},
    amr             => join( ' ', @{ $grant->{amr} } ),
    acr             => $grant->{acr},
    auth_time       => $grant->{auth_time},
    approved        => undef,
    origin_ip       => undef,
    origin_ua       => undef,
    factor_failures => 0
  } );
  return {
    access_token => $token,
    token_type   => 'Bearer',
    expires_in   => $self->token_ttl,
    scope        => $grant->{scope}
  };
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Airlock - Embeddable device authorization (RFC 8628) with step-up second factors

=head1 VERSION

version 0.001

=head1 SYNOPSIS

    my $airlock = Airlock->new(
      clients          => { 'my-cli' => { name => 'My CLI', scopes => [qw( read admin )] } },
      verification_uri => 'https://my.example.org/airlock',
      store            => { insert => sub {...}, find => sub {...}, update => sub {...}, purge => sub {...} },
      policy           => { step_up => { admin => ['totp'] } },
      factors          => [ Airlock::Factor::Callback->new( name => 'totp', amr => 'otp', verify => sub {...} ) ],
    );

    # machine side: mount the two JSON endpoints
    my $app = $airlock->to_app;

    # human side: the host application renders its own page
    my $view  = $airlock->inspect( $typed_code, subject => $subject ) or return not_found();
    my $needs = $airlock->requirements( $view, $subject );            # ['totp']
    my $done  = $airlock->approve( $typed_code, subject => $subject, proofs => { totp => $typed_totp } );

=head1 DESCRIPTION

Airlock approves a waiting request from an already trusted session: the server
side of the OAuth 2.0 Device Authorization Grant (RFC 8628), with an optional
second factor before the approval counts.

It is a core to embed. The host application supplies who is logged in, the
approval page and where rows are kept. Airlock supplies codes, the state
machine, poll rules, one-time redemption, step-up policy, second factors and
the two machine endpoints.

A request moves C<pending> to C<approved>, C<denied> or C<expired>, and
C<approved> to C<redeemed> exactly once.

=head2 clients

Required. Who may ask. A hash of client id to C<< { name => ..., scopes => [...] } >>,
or a coderef called with a client id that returns such a hash or nothing. A
client without C<scopes> may ask for any scope.

=head2 verification_uri

Required. Where the host application serves its approval page.

=head2 store

Hash of four coderefs: C<insert>, C<find>, C<update> and optionally C<purge>.
In the changes given to C<update>, a reference to a number means "add this to
the column", which the store has to do atomically.
The contract is documented in L<Airlock::Store::Memory> and checked by
L<Airlock::Test::Store>. Default: an in-process store.

=head2 policy

An L<Airlock::Policy> or the hash to build one from. Default: no factors.

=head2 factors

The L<Airlock::Factor> objects a policy may name.

=head2 issuer

Optional. Coderef called with the grant, returning the token response as a
hash. Without it Airlock issues an opaque random token, keeps its hash in the
store and checks it with L</verify_token>.

=head2 on_event

Optional. Coderef called with a hash for C<opened>, C<approved>, C<denied>,
C<redeemed>, C<factor_failed> and C<code_miss>. Hang the audit log and rate
limits here. Events never carry codes, tokens or proofs.

=head2 now

Coderef returning the current epoch. For tests.

=head2 expires_in

Seconds a request lives. Default 600.

=head2 interval

Seconds a client has to wait between polls. Default 5.

=head2 token_ttl

Seconds an opaque token lives. Default 3600.

=head2 max_factor_failures



( run in 1.342 second using v1.01-cache-2.11-cpan-99fa8243a42 )