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