Koha/REST/V1.pm

   1 package Koha::REST::V1;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it under the
   6 # terms of the GNU General Public License as published by the Free Software
   7 # Foundation; either version 3 of the License, or (at your option) any later
   8 # version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License along
  15 # with Koha; if not, write to the Free Software Foundation, Inc.,
  16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17
  18 use Modern::Perl;
  19 use Mojo::Base 'Mojolicious';
  20
  21 use C4::Auth qw( check_cookie_auth get_session haspermission );
  22 use C4::Context;
  23 use Koha::Account::Lines;
  24 use Koha::Issues;
  25 use Koha::Holds;
  26 use Koha::OldIssues;
  27 use Koha::Patrons;
  28
  29 sub startup {
  30     my $self = shift;
  31
  32     # Force charset=utf8 in Content-Type header for JSON responses
  33     $self->types->type(json => 'application/json; charset=utf8');
  34
  35     my $secret_passphrase = C4::Context->config('api_secret_passphrase');
  36     if ($secret_passphrase) {
  37         $self->secrets([$secret_passphrase]);
  38     }
  39
  40     $self->plugin(Swagger2 => {
  41         url => $self->home->rel_file("api/v1/swagger/swagger.min.json"),
  42     });
  43 }
  44
  45 =head3 authenticate_api_request
  46
  47 Validates authentication and allows access if authorization is not required or
  48 if authorization is required and user has required permissions to access.
  49
  50 This subroutine is called before every request to API.
  51
  52 =cut
  53
  54 sub authenticate_api_request {
  55     my ($next, $c, $action_spec) = @_;
  56
  57     my ($session, $user);
  58     my $cookie = $c->cookie('CGISESSID');
  59     # Mojo doesn't use %ENV the way CGI apps do
  60     # Manually pass the remote_address to check_auth_cookie
  61     my $remote_addr = $c->tx->remote_address;
  62     my ($status, $sessionID) = check_cookie_auth(
  63                                             $cookie, undef,
  64                                             { remote_addr => $remote_addr });
  65     if ($status eq "ok") {
  66         $session = get_session($sessionID);
  67         $user = Koha::Patrons->find($session->param('number'));
  68         $c->stash('koha.user' => $user);
  69     }
  70     else {
  71         return $c->render_swagger(
  72             { error => "Authentication failure." },
  73             {},
  74             401
  75         ) if $cookie and $action_spec->{'x-koha-authorization'};
  76     }
  77
  78     return $next->($c) unless $action_spec->{'x-koha-authorization'};
  79     unless ($user) {
  80         return $c->render_swagger({ error => "Authentication required." },{},401);
  81     }
  82
  83     my $authorization = $action_spec->{'x-koha-authorization'};
  84     return $next->($c) if allow_owner($c, $authorization, $user);
  85     return $next->($c) if allow_guarantor($c, $authorization, $user);
  86
  87     my $permissions = $authorization->{'permissions'};
  88     return $next->($c) if C4::Auth::haspermission($user->userid, $permissions);
  89     return $c->render_swagger(
  90         { error => "Authorization failure. Missing required permission(s).",
  91           required_permissions => $permissions },
  92         {},
  93         403
  94     );
  95 }
  96
  97 =head3 allow_owner
  98
  99 Allows access to object for its owner.
 100
 101 There are endpoints that should allow access for the object owner even if they
 102 do not have the required permission, e.g. access an own reserve. This can be
 103 achieved by defining the operation as follows:
 104
 105 "/holds/{reserve_id}": {
 106     "get": {
 107         ...,
 108         "x-koha-authorization": {
 109             "allow-owner": true,
 110             "permissions": {
 111                 "borrowers": "1"
 112             }
 113         }
 114     }
 115 }
 116
 117 =cut
 118
 119 sub allow_owner {
 120     my ($c, $authorization, $user) = @_;
 121
 122     return unless $authorization->{'allow-owner'};
 123
 124     return check_object_ownership($c, $user) if $user and $c;
 125 }
 126
 127 =head3 allow_guarantor
 128
 129 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
 130 guarantees.
 131
 132 =cut
 133
 134 sub allow_guarantor {
 135     my ($c, $authorization, $user) = @_;
 136
 137     if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
 138         return;
 139     }
 140
 141     my $guarantees = $user->guarantees->as_list;
 142     foreach my $guarantee (@{$guarantees}) {
 143         return 1 if check_object_ownership($c, $guarantee);
 144     }
 145 }
 146
 147 =head3 check_object_ownership
 148
 149 Determines ownership of an object from request parameters.
 150
 151 As introducing an endpoint that allows access for object's owner; if the
 152 parameter that will be used to determine ownership is not already inside
 153 $parameters, add a new subroutine that checks the ownership and extend
 154 $parameters to contain a key with parameter_name and a value of a subref to
 155 the subroutine that you created.
 156
 157 =cut
 158
 159 sub check_object_ownership {
 160     my ($c, $user) = @_;
 161
 162     return if not $c or not $user;
 163
 164     my $parameters = {
 165         accountlines_id => \&_object_ownership_by_accountlines_id,
 166         borrowernumber  => \&_object_ownership_by_borrowernumber,
 167         checkout_id     => \&_object_ownership_by_checkout_id,
 168         reserve_id      => \&_object_ownership_by_reserve_id,
 169     };
 170
 171     foreach my $param (keys $parameters) {
 172         my $check_ownership = $parameters->{$param};
 173         if ($c->stash($param)) {
 174             return &$check_ownership($c, $user, $c->stash($param));
 175         }
 176         elsif ($c->param($param)) {
 177             return &$check_ownership($c, $user, $c->param($param));
 178         }
 179         elsif ($c->req->json && $c->req->json->{$param}) {
 180             return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
 181         }
 182     }
 183 }
 184
 185 =head3 _object_ownership_by_accountlines_id
 186
 187 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
 188 belongs to C<$user>.
 189
 190 =cut
 191
 192 sub _object_ownership_by_accountlines_id {
 193     my ($c, $user, $accountlines_id) = @_;
 194
 195     my $accountline = Koha::Account::Lines->find($accountlines_id);
 196     return $accountline && $user->borrowernumber == $accountline->borrowernumber;
 197 }
 198
 199 =head3 _object_ownership_by_borrowernumber
 200
 201 Compares C<$borrowernumber> to currently logged in C<$user>.
 202
 203 =cut
 204
 205 sub _object_ownership_by_borrowernumber {
 206     my ($c, $user, $borrowernumber) = @_;
 207
 208     return $user->borrowernumber == $borrowernumber;
 209 }
 210
 211 =head3 _object_ownership_by_checkout_id
 212
 213 First, attempts to find a Koha::Issue-object by C<$issue_id>. If we find one,
 214 compare its borrowernumber to currently logged in C<$user>. However, if an issue
 215 is not found, attempt to find a Koha::OldIssue-object instead and compare its
 216 borrowernumber to currently logged in C<$user>.
 217
 218 =cut
 219
 220 sub _object_ownership_by_checkout_id {
 221     my ($c, $user, $issue_id) = @_;
 222
 223     my $issue = Koha::Issues->find($issue_id);
 224     $issue = Koha::OldIssues->find($issue_id) unless $issue;
 225     return $issue && $issue->borrowernumber
 226             && $user->borrowernumber == $issue->borrowernumber;
 227 }
 228
 229 =head3 _object_ownership_by_reserve_id
 230
 231 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
 232 belongs to C<$user>.
 233
 234 TODO: Also compare against old_reserves
 235
 236 =cut
 237
 238 sub _object_ownership_by_reserve_id {
 239     my ($c, $user, $reserve_id) = @_;
 240
 241     my $reserve = Koha::Holds->find($reserve_id);
 242     return $reserve && $user->borrowernumber == $reserve->borrowernumber;
 243 }
 244
 245 1;