application/api/ApiUtils.php

   1 <?php
   2
   3 namespace Shaarli\Api;
   4
   5 use Shaarli\Api\Exceptions\ApiAuthorizationException;
   6 use Shaarli\Bookmark\Bookmark;
   7 use Shaarli\Http\Base64Url;
   8
   9 /**
  10  * REST API utilities
  11  */
  12 class ApiUtils
  13 {
  14     /**
  15      * Validates a JWT token authenticity.
  16      *
  17      * @param string $token  JWT token extracted from the headers.
  18      * @param string $secret API secret set in the settings.
  19      *
  20      * @return bool true on success
  21      *
  22      * @throws ApiAuthorizationException the token is not valid.
  23      */
  24     public static function validateJwtToken($token, $secret)
  25     {
  26         $parts = explode('.', $token);
  27         if (count($parts) != 3 || strlen($parts[0]) == 0 || strlen($parts[1]) == 0) {
  28             throw new ApiAuthorizationException('Malformed JWT token');
  29         }
  30
  31         $genSign = Base64Url::encode(hash_hmac('sha512', $parts[0] . '.' . $parts[1], $secret, true));
  32         if ($parts[2] != $genSign) {
  33             throw new ApiAuthorizationException('Invalid JWT signature');
  34         }
  35
  36         $header = json_decode(Base64Url::decode($parts[0]));
  37         if ($header === null) {
  38             throw new ApiAuthorizationException('Invalid JWT header');
  39         }
  40
  41         $payload = json_decode(Base64Url::decode($parts[1]));
  42         if ($payload === null) {
  43             throw new ApiAuthorizationException('Invalid JWT payload');
  44         }
  45
  46         if (
  47             empty($payload->iat)
  48             || $payload->iat > time()
  49             || time() - $payload->iat > ApiMiddleware::$TOKEN_DURATION
  50         ) {
  51             throw new ApiAuthorizationException('Invalid JWT issued time');
  52         }
  53
  54         return true;
  55     }
  56
  57     /**
  58      * Format a Link for the REST API.
  59      *
  60      * @param Bookmark $bookmark Bookmark data read from the datastore.
  61      * @param string   $indexUrl Shaarli's index URL (used for relative URL).
  62      *
  63      * @return array Link data formatted for the REST API.
  64      */
  65     public static function formatLink($bookmark, $indexUrl)
  66     {
  67         $out['id'] = $bookmark->getId();
  68         // Not an internal link
  69         if (! $bookmark->isNote()) {
  70             $out['url'] = $bookmark->getUrl();
  71         } else {
  72             $out['url'] = rtrim($indexUrl, '/') . '/' . ltrim($bookmark->getUrl(), '/');
  73         }
  74         $out['shorturl'] = $bookmark->getShortUrl();
  75         $out['title'] = $bookmark->getTitle();
  76         $out['description'] = $bookmark->getDescription();
  77         $out['tags'] = $bookmark->getTags();
  78         $out['private'] = $bookmark->isPrivate();
  79         $out['created'] = $bookmark->getCreated()->format(\DateTime::ATOM);
  80         if (! empty($bookmark->getUpdated())) {
  81             $out['updated'] = $bookmark->getUpdated()->format(\DateTime::ATOM);
  82         } else {
  83             $out['updated'] = '';
  84         }
  85         return $out;
  86     }
  87
  88     /**
  89      * Convert a link given through a request, to a valid Bookmark for the datastore.
  90      *
  91      * If no URL is provided, it will generate a local note URL.
  92      * If no title is provided, it will use the URL as title.
  93      *
  94      * @param array|null  $input          Request Link.
  95      * @param bool        $defaultPrivate Setting defined if a bookmark is private by default.
  96      *
  97      * @return Bookmark instance.
  98      */
  99     public static function buildBookmarkFromRequest(?array $input, bool $defaultPrivate): Bookmark
 100     {
 101         $bookmark = new Bookmark();
 102         $url = ! empty($input['url']) ? cleanup_url($input['url']) : '';
 103         if (isset($input['private'])) {
 104             $private = filter_var($input['private'], FILTER_VALIDATE_BOOLEAN);
 105         } else {
 106             $private = $defaultPrivate;
 107         }
 108
 109         $bookmark->setTitle(! empty($input['title']) ? $input['title'] : '');
 110         $bookmark->setUrl($url);
 111         $bookmark->setDescription(! empty($input['description']) ? $input['description'] : '');
 112         $bookmark->setTags(! empty($input['tags']) ? $input['tags'] : []);
 113         $bookmark->setPrivate($private);
 114
 115         $created = \DateTime::createFromFormat(\DateTime::ATOM, $input['created'] ?? '');
 116         if ($created instanceof \DateTimeInterface) {
 117             $bookmark->setCreated($created);
 118         }
 119         $updated = \DateTime::createFromFormat(\DateTime::ATOM, $input['updated'] ?? '');
 120         if ($updated instanceof \DateTimeInterface) {
 121             $bookmark->setUpdated($updated);
 122         }
 123
 124         return $bookmark;
 125     }
 126
 127     /**
 128      * Update link fields using an updated link object.
 129      *
 130      * @param Bookmark $oldLink data
 131      * @param Bookmark $newLink data
 132      *
 133      * @return Bookmark $oldLink updated with $newLink values
 134      */
 135     public static function updateLink($oldLink, $newLink)
 136     {
 137         $oldLink->setTitle($newLink->getTitle());
 138         $oldLink->setUrl($newLink->getUrl());
 139         $oldLink->setDescription($newLink->getDescription());
 140         $oldLink->setTags($newLink->getTags());
 141         $oldLink->setPrivate($newLink->isPrivate());
 142
 143         return $oldLink;
 144     }
 145
 146     /**
 147      * Format a Tag for the REST API.
 148      *
 149      * @param string $tag         Tag name
 150      * @param int    $occurrences Number of bookmarks using this tag
 151      *
 152      * @return array Link data formatted for the REST API.
 153      */
 154     public static function formatTag($tag, $occurences)
 155     {
 156         return [
 157             'name'       => $tag,
 158             'occurrences' => $occurences,
 159         ];
 160     }
 161 }