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