path: root/Bugzilla/User/APIKey.pm

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This Source Code Form is "Incompatible With Secondary Licenses", as
# defined by the Mozilla Public License, v. 2.0.

package Bugzilla::User::APIKey;

use 5.10.1;
use strict;
use warnings;

use parent qw(Bugzilla::Object);

use Bugzilla::Constants;
use Bugzilla::User;
use Bugzilla::Util qw(generate_random_password trim bz_crypt);

#####################################################################
# Overriden Constants that are used as methods
#####################################################################

use constant DB_TABLE   => 'user_api_keys';
use constant DB_COLUMNS => qw(
  id
  user_id
  api_key
  description
  revoked
  last_used
  banned
);

use constant UPDATE_COLUMNS => qw(description revoked last_used banned);
use constant VALIDATORS     => {
  api_key     => \&_check_api_key,
  description => \&_check_description,
  revoked     => \&Bugzilla::Object::check_boolean,
  banned      => \&Bugzilla::Object::check_boolean,
};
use constant LIST_ORDER => 'id';
use constant NAME_FIELD => 'api_key';

# turn off auditing and exclude these objects from memcached
use constant {
  AUDIT_CREATES => 0,
  AUDIT_UPDATES => 0,
  AUDIT_REMOVES => 0,
  USE_MEMCACHED => 0
};

# Accessors
sub id          { return $_[0]->{id} }
sub user_id     { return $_[0]->{user_id} }
sub api_key     { return $_[0]->{api_key} }
sub description { return $_[0]->{description} }
sub revoked     { return $_[0]->{revoked} }
sub last_used   { return $_[0]->{last_used} }
sub banned      { return $_[0]->{banned} }

# Helpers
sub user {
  my $self = shift;
  $self->{user} //= Bugzilla::User->new({id => $self->user_id, cache => 1});
  return $self->{user};
}

sub update_last_used {
  my $self = shift;
  my $timestamp
    = shift || Bugzilla->dbh->selectrow_array('SELECT LOCALTIMESTAMP(0)');

  ## RED HAT EXTENSION START 1660438
  # This does not need to be protected from serialization conflicts
  my $dbh = Bugzilla->dbh;
  $dbh->bz_start_transaction(1);
  $self->set('last_used', $timestamp);
  $self->update;
  $dbh->bz_commit_transaction();
  ## RED HAT EXTENSION END 1660438
  return;
}

# Setters
sub set_description { $_[0]->set('description', $_[1]); }
sub set_revoked     { $_[0]->set('revoked',     $_[1]); }

sub set_banned {
 my($self, $input) = @_;

  Bugzilla->user->in_group('admin')
    || ThrowUserError("auth_failure",
    {group => "admin", action => "run", object => "apikey"});

  ThrowUserError("api_key_cannot_unban") if($self->banned() && !$input);
  $self->set('banned', $input);
}

# Validators
sub _check_api_key     { return $_[1]; }
sub _check_description { return trim($_[1]) || ''; }

sub create {
  my $class = shift;
  my $dbh   = Bugzilla->dbh;

  $dbh->bz_start_transaction();

  $class->check_required_create_fields(@_);

  my $key = generate_random_password(40);
  $_[0]->{api_key} = bz_crypt($key, Bugzilla->localconfig->{'site_wide_secret'},
    PASSWORD_DIGEST_ALGORITHM);

  my $params = $class->run_create_validators(@_);

  my $api_key = $class->insert_create_data($params);

  $api_key->{key} = $key;
  $dbh->bz_commit_transaction();

  return $api_key;
}

1;

__END__

=head1 NAME

Bugzilla::User::APIKey - Model for an api key belonging to a user.

=head1 SYNOPSIS

  use Bugzilla::User::APIKey;

  my $api_key = Bugzilla::User::APIKey->new($id);
  my $api_key = Bugzilla::User::APIKey->new({ name => $api_key });

  # Class Functions
  $user_api_key = Bugzilla::User::APIKey->create({
      description => $description,
  });

=head1 DESCRIPTION

This package handles Bugzilla User::APIKey.

C<Bugzilla::User::APIKey> is an implementation of L<Bugzilla::Object>, and
thus provides all the methods of L<Bugzilla::Object> in addition to the methods
listed below.

=head1 METHODS

=head2 Accessor Methods

=over

=item C<id>

The internal id of the api key.

=item C<user>

The Bugzilla::User object that this api key belongs to.

=item C<user_id>

The user id that this api key belongs to.

=item C<api_key>

The API key, which is a random string.

=item C<description>

An optional string that lets the user describe what a key is used for.
For example: "Dashboard key", "Application X key".

=item C<revoked>

If true, this api key cannot be used.

=item C<banned>

If true, this api key has been revoked by an admin and cannot be used.

=item C<last_used>

The date that this key was last used. undef if never used.

=item C<update_last_used>

Updates the last used value to the current timestamp. This is updated even
if the RPC call resulted in an error. It is not updated when the description
or the revoked flag is changed.

=item C<set_description>

Sets the new description

=item C<set_revoked>

Sets the revoked flag

=item C<set_banned>

Sets the banned flag, you must be in the admin group to set this field.

=back


=head1 CLASS FUNCTIONS

These are functions that are not called on a User object, but instead are
called "statically," just like a normal procedural function.

=over 4

=item C<create>

The same as L<Bugzilla::Object/create>.

Params: description - What the key is used for
        user_id - The uid of the user this key belongs to.

=back