1 package Koha::REST::V1;
3 # This file is part of Koha.
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
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.
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.
19 use Mojo::Base 'Mojolicious';
21 use C4::Auth qw( check_cookie_auth get_session haspermission );
23 use Koha::Account::Lines;
31 Koha::REST::V1 - Main v.1 REST api class
39 Overloaded Mojolicious->startup method. It is called at application startup.
46 # Force charset=utf8 in Content-Type header for JSON responses
47 $self->types->type(json => 'application/json; charset=utf8');
49 my $secret_passphrase = C4::Context->config('api_secret_passphrase');
50 if ($secret_passphrase) {
51 $self->secrets([$secret_passphrase]);
54 $self->plugin(Swagger2 => {
55 url => $self->home->rel_file("api/v1/swagger/swagger.min.json"),
59 =head3 authenticate_api_request
61 Validates authentication and allows access if authorization is not required or
62 if authorization is required and user has required permissions to access.
64 This subroutine is called before every request to API.
68 sub authenticate_api_request {
69 my ($next, $c, $action_spec) = @_;
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(
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);
85 return $c->render_swagger(
86 { error => "Authentication failure." },
89 ) if $cookie and $action_spec->{'x-koha-authorization'};
92 return $next->($c) unless $action_spec->{'x-koha-authorization'};
94 return $c->render_swagger({ error => "Authentication required." },{},401);
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 },
112 Allows access to object for its owner.
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:
118 "/holds/{reserve_id}": {
121 "x-koha-authorization": {
133 my ($c, $authorization, $user) = @_;
135 return unless $authorization->{'allow-owner'};
137 return check_object_ownership($c, $user) if $user and $c;
140 =head3 allow_guarantor
142 Same as "allow_owner", but checks if the object is owned by one of C<$user>'s
147 sub allow_guarantor {
148 my ($c, $authorization, $user) = @_;
150 if (!$c || !$user || !$authorization || !$authorization->{'allow-guarantor'}){
154 my $guarantees = $user->guarantees->as_list;
155 foreach my $guarantee (@{$guarantees}) {
156 return 1 if check_object_ownership($c, $guarantee);
160 =head3 check_object_ownership
162 Determines ownership of an object from request parameters.
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.
172 sub check_object_ownership {
175 return if not $c or not $user;
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,
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));
189 elsif ($c->param($param)) {
190 return &$check_ownership($c, $user, $c->param($param));
192 elsif ($c->req->json && $c->req->json->{$param}) {
193 return 1 if &$check_ownership($c, $user, $c->req->json->{$param});
198 =head3 _object_ownership_by_accountlines_id
200 Finds a Koha::Account::Line-object by C<$accountlines_id> and checks if it
205 sub _object_ownership_by_accountlines_id {
206 my ($c, $user, $accountlines_id) = @_;
208 my $accountline = Koha::Account::Lines->find($accountlines_id);
209 return $accountline && $user->borrowernumber == $accountline->borrowernumber;
212 =head3 _object_ownership_by_borrowernumber
214 Compares C<$borrowernumber> to currently logged in C<$user>.
218 sub _object_ownership_by_borrowernumber {
219 my ($c, $user, $borrowernumber) = @_;
221 return $user->borrowernumber == $borrowernumber;
224 =head3 _object_ownership_by_checkout_id
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>.
233 sub _object_ownership_by_checkout_id {
234 my ($c, $user, $issue_id) = @_;
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;
242 =head3 _object_ownership_by_reserve_id
244 Finds a Koha::Hold-object by C<$reserve_id> and checks if it
247 TODO: Also compare against old_reserves
251 sub _object_ownership_by_reserve_id {
252 my ($c, $user, $reserve_id) = @_;
254 my $reserve = Koha::Holds->find($reserve_id);
255 return $reserve && $user->borrowernumber == $reserve->borrowernumber;