1# This Source Code Form is subject to the terms of the Mozilla Public
2# License, v. 2.0. If a copy of the MPL was not distributed with this
3# file, You can obtain one at http://mozilla.org/MPL/2.0/.
4#
5# This Source Code Form is "Incompatible With Secondary Licenses", as
6# defined by the Mozilla Public License, v. 2.0.
7
8package Bugzilla::User::APIKey;
9
10use 5.10.1;
11use strict;
12use warnings;
13
14use parent qw(Bugzilla::Object);
15
16use Bugzilla::User;
17use Bugzilla::Util qw(generate_random_password trim);
18
19#####################################################################
20# Overriden Constants that are used as methods
21#####################################################################
22
23use constant DB_TABLE       => 'user_api_keys';
24use constant DB_COLUMNS     => qw(
25    id
26    user_id
27    api_key
28    description
29    revoked
30    last_used
31);
32
33use constant UPDATE_COLUMNS => qw(description revoked last_used);
34use constant VALIDATORS     => {
35    api_key     => \&_check_api_key,
36    description => \&_check_description,
37    revoked     => \&Bugzilla::Object::check_boolean,
38};
39use constant LIST_ORDER     => 'id';
40use constant NAME_FIELD     => 'api_key';
41
42# turn off auditing and exclude these objects from memcached
43use constant { AUDIT_CREATES => 0,
44               AUDIT_UPDATES => 0,
45               AUDIT_REMOVES => 0,
46               USE_MEMCACHED => 0 };
47
48# Accessors
49sub id            { return $_[0]->{id}          }
50sub user_id       { return $_[0]->{user_id}     }
51sub api_key       { return $_[0]->{api_key}     }
52sub description   { return $_[0]->{description} }
53sub revoked       { return $_[0]->{revoked}     }
54sub last_used     { return $_[0]->{last_used}   }
55
56# Helpers
57sub user {
58    my $self = shift;
59    $self->{user} //= Bugzilla::User->new({name => $self->user_id, cache => 1});
60    return $self->{user};
61}
62
63sub update_last_used {
64    my $self = shift;
65    my $timestamp = shift
66        || Bugzilla->dbh->selectrow_array('SELECT LOCALTIMESTAMP(0)');
67    $self->set('last_used', $timestamp);
68    $self->update;
69}
70
71# Setters
72sub set_description { $_[0]->set('description', $_[1]); }
73sub set_revoked     { $_[0]->set('revoked',     $_[1]); }
74
75# Validators
76sub _check_api_key     { return generate_random_password(40); }
77sub _check_description { return trim($_[1]) || '';   }
781;
79
80__END__
81
82=head1 NAME
83
84Bugzilla::User::APIKey - Model for an api key belonging to a user.
85
86=head1 SYNOPSIS
87
88  use Bugzilla::User::APIKey;
89
90  my $api_key = Bugzilla::User::APIKey->new($id);
91  my $api_key = Bugzilla::User::APIKey->new({ name => $api_key });
92
93  # Class Functions
94  $user_api_key = Bugzilla::User::APIKey->create({
95      description => $description,
96  });
97
98=head1 DESCRIPTION
99
100This package handles Bugzilla User::APIKey.
101
102C<Bugzilla::User::APIKey> is an implementation of L<Bugzilla::Object>, and
103thus provides all the methods of L<Bugzilla::Object> in addition to the methods
104listed below.
105
106=head1 METHODS
107
108=head2 Accessor Methods
109
110=over
111
112=item C<id>
113
114The internal id of the api key.
115
116=item C<user>
117
118The Bugzilla::User object that this api key belongs to.
119
120=item C<user_id>
121
122The user id that this api key belongs to.
123
124=item C<api_key>
125
126The API key, which is a random string.
127
128=item C<description>
129
130An optional string that lets the user describe what a key is used for.
131For example: "Dashboard key", "Application X key".
132
133=item C<revoked>
134
135If true, this api key cannot be used.
136
137=item C<last_used>
138
139The date that this key was last used. undef if never used.
140
141=item C<update_last_used>
142
143Updates the last used value to the current timestamp. This is updated even
144if the RPC call resulted in an error. It is not updated when the description
145or the revoked flag is changed.
146
147=item C<set_description>
148
149Sets the new description
150
151=item C<set_revoked>
152
153Sets the revoked flag
154
155=back
156