| 1 | package WWW::Suffit::Server::API::V1; | ||
| 2 | use strict; | ||
| 3 | use utf8; | ||
| 4 | |||
| 5 | =encoding utf8 | ||
| 6 | |||
| 7 | =head1 NAME | ||
| 8 | |||
| 9 | WWW::Suffit::Server::API::V1 - The public Suffit API controller, version 1 | ||
| 10 | |||
| 11 | =head1 SYNOPSIS | ||
| 12 | |||
| 13 | use WWW::Suffit::Server::API::V1; | ||
| 14 | |||
| 15 | =head1 DESCRIPTION | ||
| 16 | |||
| 17 | The public Suffit API controller, version 1 | ||
| 18 | |||
| 19 | =head1 METHODS | ||
| 20 | |||
| 21 | List of internal methods | ||
| 22 | |||
| 23 | =head2 authn | ||
| 24 | |||
| 25 | See L</"POST /api/v1/authn"> | ||
| 26 | |||
| 27 | =head2 authz | ||
| 28 | |||
| 29 | See L</"POST /api/v1/authz"> | ||
| 30 | |||
| 31 | =head2 public_key | ||
| 32 | |||
| 33 | See L</"GET /api/v1/publicKey"> | ||
| 34 | |||
| 35 | =head1 API METHODS | ||
| 36 | |||
| 37 | List of API methods | ||
| 38 | |||
| 39 | =head2 POST /api/v1/authn | ||
| 40 | |||
| 41 | This method performs authentication of the remote user | ||
| 42 | |||
| 43 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 44 | -X POST -d '{ | ||
| 45 | "username": "bob", | ||
| 46 | "password": "bob", | ||
| 47 | "address": "1.2.3.4", | ||
| 48 | "encrypted": false | ||
| 49 | }' \ | ||
| 50 | https://localhost:8695/api/v1/authn | ||
| 51 | |||
| 52 | > POST /api/v1/authn HTTP/1.1 | ||
| 53 | > Host: localhost:8695 | ||
| 54 | > User-Agent: curl/7.68.0 | ||
| 55 | > Accept: */* | ||
| 56 | > Authorization: Bearer eyJh...Ggns | ||
| 57 | > Content-Length: 120 | ||
| 58 | > Content-Type: application/x-www-form-urlencoded | ||
| 59 | > | ||
| 60 | < HTTP/1.1 200 OK | ||
| 61 | < Content-Length: 30 | ||
| 62 | < Content-Type: application/json;charset=UTF-8 | ||
| 63 | < Date: Wed, 14 Aug 2024 10:18:22 GMT | ||
| 64 | < Server: OWL/1.11 | ||
| 65 | < | ||
| 66 | { | ||
| 67 | "code": "E0000", | ||
| 68 | "status": true | ||
| 69 | } | ||
| 70 | |||
| 71 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 72 | -X POST -d '{ | ||
| 73 | "username": "bob", | ||
| 74 | "password": "incorrect", | ||
| 75 | "address": "1.2.3.4", | ||
| 76 | "encrypted": false | ||
| 77 | }' \ | ||
| 78 | https://localhost:8695/api/v1/authn | ||
| 79 | |||
| 80 | > POST /api/v1/authn HTTP/1.1 | ||
| 81 | > Host: localhost:8695 | ||
| 82 | > User-Agent: curl/7.68.0 | ||
| 83 | > Accept: */* | ||
| 84 | > Authorization: Bearer eyJh...Ggns | ||
| 85 | > Content-Length: 126 | ||
| 86 | > Content-Type: application/x-www-form-urlencoded | ||
| 87 | > | ||
| 88 | < HTTP/1.1 401 Unauthorized | ||
| 89 | < Content-Length: 74 | ||
| 90 | < Content-Type: application/json;charset=UTF-8 | ||
| 91 | < Date: Wed, 14 Aug 2024 10:22:11 GMT | ||
| 92 | < Server: OWL/1.11 | ||
| 93 | < | ||
| 94 | { | ||
| 95 | "code": "E1326", | ||
| 96 | "message": "Incorrect username or password", | ||
| 97 | "status": false | ||
| 98 | } | ||
| 99 | |||
| 100 | =head2 POST /api/v1/authz | ||
| 101 | |||
| 102 | This method performs authorization and checks access grants of the remote user | ||
| 103 | |||
| 104 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 105 | -X POST -d '{ | ||
| 106 | "username": "bob", | ||
| 107 | "method": "GET", | ||
| 108 | "url": "https://owl.localhost:8695/stuff", | ||
| 109 | "address": "1.2.3.4", | ||
| 110 | "headers": { | ||
| 111 | "Accept": "text/html,text/plain", | ||
| 112 | "Connection": "keep-alive", | ||
| 113 | "Host": "localhost:8695" | ||
| 114 | } | ||
| 115 | }' \ | ||
| 116 | https://localhost:8695/api/v1/authz | ||
| 117 | |||
| 118 | > POST /api/v1/authz HTTP/1.1 | ||
| 119 | > Host: localhost:8695 | ||
| 120 | > User-Agent: curl/7.68.0 | ||
| 121 | > Accept: */* | ||
| 122 | > Authorization: Bearer eyJh...Ggns | ||
| 123 | > Content-Length: 296 | ||
| 124 | > Content-Type: application/x-www-form-urlencoded | ||
| 125 | > | ||
| 126 | < HTTP/1.1 200 OK | ||
| 127 | < Content-Length: 30 | ||
| 128 | < Content-Type: application/json;charset=UTF-8 | ||
| 129 | < Date: Wed, 14 Aug 2024 10:40:17 GMT | ||
| 130 | < Server: OWL/1.11 | ||
| 131 | < | ||
| 132 | { | ||
| 133 | "code": "E0000", | ||
| 134 | "status": true | ||
| 135 | } | ||
| 136 | |||
| 137 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 138 | -X POST -d '{ | ||
| 139 | "username": "bob", | ||
| 140 | "method": "GET", | ||
| 141 | "url": "https://localhost:8695/api/check", | ||
| 142 | "address": "1.2.3.4", | ||
| 143 | "verbose": true | ||
| 144 | }' \ | ||
| 145 | https://localhost:8695/api/v1/authz | ||
| 146 | |||
| 147 | > POST /api/v1/authz HTTP/1.1 | ||
| 148 | > Host: localhost:8695 | ||
| 149 | > User-Agent: curl/7.68.0 | ||
| 150 | > Accept: */* | ||
| 151 | > Authorization: Bearer eyJh...Ggns | ||
| 152 | > Content-Length: 166 | ||
| 153 | > Content-Type: application/x-www-form-urlencoded | ||
| 154 | > | ||
| 155 | < HTTP/1.1 200 OK | ||
| 156 | < Content-Length: 289 | ||
| 157 | < Content-Type: application/json;charset=UTF-8 | ||
| 158 | < Date: Wed, 14 Aug 2024 10:56:45 GMT | ||
| 159 | < Server: OWL/1.11 | ||
| 160 | < | ||
| 161 | { | ||
| 162 | "address": "1.2.3.4", | ||
| 163 | "base": "https://localhost:8695", | ||
| 164 | "code": "E0000", | ||
| 165 | "email": "bob@example.com", | ||
| 166 | "email_md5": "4b9bb80620f03eb3719e0a061c14283d", | ||
| 167 | "expires": 1723633005, | ||
| 168 | "groups": [], | ||
| 169 | "method": "GET", | ||
| 170 | "name": "Bob Bob", | ||
| 171 | "path": "/api/check", | ||
| 172 | "role": "Test user", | ||
| 173 | "status": true, | ||
| 174 | "uid": 13, | ||
| 175 | "username": "bob" | ||
| 176 | } | ||
| 177 | |||
| 178 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 179 | -X POST -d '{ | ||
| 180 | "username": "unknown", | ||
| 181 | "method": "GET", | ||
| 182 | "url": "https://localhost:8695/api/check", | ||
| 183 | "address": "1.2.3.4" | ||
| 184 | }' \ | ||
| 185 | https://localhost:8695/api/v1/authz | ||
| 186 | |||
| 187 | > POST /api/v1/authz HTTP/1.1 | ||
| 188 | > Host: localhost:8695 | ||
| 189 | > User-Agent: curl/7.68.0 | ||
| 190 | > Accept: */* | ||
| 191 | > Authorization: Bearer eyJh...Ggns | ||
| 192 | > Content-Length: 145 | ||
| 193 | > Content-Type: application/x-www-form-urlencoded | ||
| 194 | > | ||
| 195 | < HTTP/1.1 401 Unauthorized | ||
| 196 | < Content-Length: 58 | ||
| 197 | < Content-Type: application/json;charset=UTF-8 | ||
| 198 | < Date: Wed, 14 Aug 2024 10:43:43 GMT | ||
| 199 | < Server: OWL/1.11 | ||
| 200 | < | ||
| 201 | { | ||
| 202 | "code": "E1310", | ||
| 203 | "message": "User not found", | ||
| 204 | "status": false | ||
| 205 | } | ||
| 206 | |||
| 207 | =head2 GET /api/v1/publicKey | ||
| 208 | |||
| 209 | Get RSA public key of user (of the token issuer) | ||
| 210 | |||
| 211 | # curl -v -H "Authorization: Bearer eyJh...Ggns" \ | ||
| 212 | https://localhost:8695/api/v1/publicKey | ||
| 213 | |||
| 214 | > GET /api/v1/publicKey HTTP/1.1 | ||
| 215 | > Host: localhost:8695 | ||
| 216 | > User-Agent: curl/7.68.0 | ||
| 217 | > Accept: */* | ||
| 218 | > Authorization: Bearer eyJh...Ggns | ||
| 219 | > | ||
| 220 | < HTTP/1.1 200 OK | ||
| 221 | < Content-Length: 306 | ||
| 222 | < Content-Type: application/json;charset=UTF-8 | ||
| 223 | < Date: Wed, 14 Aug 2024 11:02:33 GMT | ||
| 224 | < Server: OWL/1.11 | ||
| 225 | < | ||
| 226 | { | ||
| 227 | "code": "E0000", | ||
| 228 | "public_key": "-----BEGIN RSA PUBLIC KEY-----...", | ||
| 229 | "status": true | ||
| 230 | } | ||
| 231 | |||
| 232 | =head1 ERROR CODES | ||
| 233 | |||
| 234 | List of V1 Suffit API error codes | ||
| 235 | |||
| 236 | API | HTTP | DESCRIPTION | ||
| 237 | -------+-------+------------------------------------------------- | ||
| 238 | E1100 [404] No RSA public key found | ||
| 239 | E1101 [400] No RSA private key found | ||
| 240 | E1102 [500] RSA decrypt error | ||
| 241 | E1103 [ * ] Incorrect username or password | ||
| 242 | E1104 [ * ] Access denied (authz) | ||
| 243 | E1105 [ * ] Access denied by realm restrictions (access) | ||
| 244 | E1106 [---] Reserved | ||
| 245 | E1107 [---] Reserved | ||
| 246 | E1108 [---] Reserved | ||
| 247 | E1109 [---] Reserved | ||
| 248 | |||
| 249 | B<*> -- this code will be defined later on the interface side | ||
| 250 | |||
| 251 | See also list of common Suffit API error codes in L<WWW::Suffit::API/"ERROR CODES"> | ||
| 252 | |||
| 253 | =head1 HISTORY | ||
| 254 | |||
| 255 | See C<Changes> file | ||
| 256 | |||
| 257 | =head1 TO DO | ||
| 258 | |||
| 259 | See C<TODO> file | ||
| 260 | |||
| 261 | =head1 SEE ALSO | ||
| 262 | |||
| 263 | L<Mojolicious>, L<WWW::Suffit>, L<WWW::Suffit::Server>, L<WWW::Suffit::API> | ||
| 264 | |||
| 265 | =head1 AUTHOR | ||
| 266 | |||
| 267 | Serż Minus (Sergey Lepenkov) L<https://www.serzik.com> E<lt>abalama@cpan.orgE<gt> | ||
| 268 | |||
| 269 | =head1 COPYRIGHT | ||
| 270 | |||
| 271 | Copyright (C) 1998-2026 D&D Corporation | ||
| 272 | |||
| 273 | =head1 LICENSE | ||
| 274 | |||
| 275 | This program is distributed under the terms of the Artistic License Version 2.0 | ||
| 276 | |||
| 277 | See the C<LICENSE> file or L<https://opensource.org/license/artistic-2-0> for details | ||
| 278 | |||
| 279 | =cut | ||
| 280 | |||
| 281 | use Mojo::Base 'Mojolicious::Controller'; | ||
| 282 | |||
| 283 | use Mojo::Path; | ||
| 284 | use Mojo::URL; | ||
| 285 | |||
| 286 | use Acrux::RefUtil qw/ is_hash_ref /; | ||
| 287 | |||
| 288 | use WWW::Suffit::RSA; | ||
| 289 | |||
| 290 | sub authn { | ||
| 291 | my $self = shift; | ||
| 292 | my $username = $self->req->json('/username') // ''; | ||
| 293 | my $password = $self->req->json('/password') // ''; | ||
| 294 | my $address = $self->req->json('/address') // ''; | ||
| 295 | my $encrypted = $self->req->json('/encrypted') || 0; | ||
| 296 | my $cachekey = $self->stash('cachekey'); | ||
| 297 | my $authdb = $self->authdb; | ||
| 298 | my $acc_user = $authdb->user($self->stash('username'), $cachekey); | ||
| 299 | my $public_key = $acc_user->public_key // ''; | ||
| 300 | my $private_key = $acc_user->private_key // ''; | ||
| 301 | $authdb->clean; | ||
| 302 | |||
| 303 | # Password decrypt | ||
| 304 | if ($encrypted && length($password)) { | ||
| 305 | return $self->reply->json_error(400 => "E1100" => "No RSA public key found") unless length $public_key; | ||
| 306 | return $self->reply->json_error(400 => "E1101" => "No RSA private key found") unless length $private_key; | ||
| 307 | my $rsa = WWW::Suffit::RSA->new->private_key($private_key); | ||
| 308 | $password = $rsa->decrypt($password); # RSA Decrypt password | ||
| 309 | return $self->reply->json_error(500 => "E1102" => $rsa->error || "RSA decrypt error") if $rsa->error; | ||
| 310 | } | ||
| 311 | |||
| 312 | # Authentication | ||
| 313 | return $self->reply->json_error( | ||
| 314 | $authdb->code, $authdb->error || "E1103: Incorrect username or password" | ||
| 315 | ) unless $authdb->authn( | ||
| 316 | u => $username, | ||
| 317 | p => $password, | ||
| 318 | k => $cachekey, | ||
| 319 | a => $address, # For check by stats | ||
| 320 | ); # Unauthenticated | ||
| 321 | |||
| 322 | # Render ok | ||
| 323 | return $self->reply->json_ok; | ||
| 324 | } | ||
| 325 | sub authz { | ||
| 326 | my $self = shift; | ||
| 327 | my $authdb = $self->authdb->clean; | ||
| 328 | my $cachekey = $self->stash('cachekey'); | ||
| 329 | my $username = $self->req->json('/username') // ''; | ||
| 330 | my $verbose = $self->req->json('/verbose') || 0; | ||
| 331 | my $url = $self->req->json('/url') // $self->base_url // ''; | ||
| 332 | my $uri = Mojo::URL->new($url); | ||
| 333 | $username = $uri->username unless length $username; | ||
| 334 | my %args = (controller => $self, username => $username, cachekey => $cachekey); | ||
| 335 | $args{address} = $self->req->json('/address') // ''; | ||
| 336 | $args{method} = $self->req->json('/method') // ''; | ||
| 337 | $args{path} = $self->req->json('/path') // | ||
| 338 | $uri->path->leading_slash(1)->trailing_slash(0)->to_string // ''; | ||
| 339 | $args{base} = $self->req->json('/base') // | ||
| 340 | $uri->path_query("")->path(Mojo::Path->new->leading_slash(0)->trailing_slash(0) )->to_string // ''; | ||
| 341 | my $headers = $self->req->json('/headers') || {}; | ||
| 342 | if (is_hash_ref($headers)) { | ||
| 343 | my %hdrs = (); | ||
| 344 | while (my ($k, $v) = each %$headers) { | ||
| 345 | $hdrs{$k} = $v if defined($v) && !ref($v); | ||
| 346 | } | ||
| 347 | $args{headers} = {%hdrs} if scalar %hdrs; | ||
| 348 | } | ||
| 349 | |||
| 350 | # Authorization (External!) | ||
| 351 | my $user = $authdb->authz( | ||
| 352 | u => $username, | ||
| 353 | 's' => 1, | ||
| 354 | k => $cachekey, | ||
| 355 | ); | ||
| 356 | return $self->reply->json_error( | ||
| 357 | $authdb->code, $authdb->error || "E1104: Access denied" | ||
| 358 | ) unless $user; # Unauthorized | ||
| 359 | #$self->log->debug($self->dumper($user)); | ||
| 360 | |||
| 361 | # Access (username is optional) | ||
| 362 | return $self->reply->json_error( | ||
| 363 | $authdb->code, $authdb->error || "E1105: Access denied by realm restrictions" | ||
| 364 | ) unless ($authdb->access(%args)); # Forbidden | ||
| 365 | |||
| 366 | # Render ok | ||
| 367 | return $self->reply->json_ok unless $verbose; | ||
| 368 | |||
| 369 | # Render user data | ||
| 370 | my %ret = $user->to_hash; | ||
| 371 | $ret{address} = $args{address} if length $args{address}; | ||
| 372 | foreach my $k (qw/method path base/) { | ||
| 373 | $ret{$k} = $args{$k} if length $args{$k}; | ||
| 374 | } | ||
| 375 | $ret{headers} = $args{headers} if exists $args{headers}; | ||
| 376 | |||
| 377 | # Ok | ||
| 378 | return $self->reply->json_ok({%ret}); | ||
| 379 | } | ||
| 380 | sub public_key { | ||
| 381 | my $self = shift; | ||
| 382 | my $username = $self->stash('username'); | ||
| 383 | my $cachekey = $self->stash('cachekey'); | ||
| 384 | my $authdb = $self->authdb; | ||
| 385 | my $public_key = $authdb->user($username, $cachekey)->public_key // ''; | ||
| 386 | return $self->reply->json_error(404 => "E1100" => "No RSA public key found") unless length $public_key; | ||
| 387 | return $self->reply->json_ok({public_key => $public_key}); | ||
| 388 | } | ||
| 389 | |||
| 390 | 1; | ||
| 391 | |||
| 392 | __END__ |