Merge pull request #16 from givebutter/givebutter/api-key-name

Add the ability to give a name to an api key and also hash the token before storing them

Author: liran-co

README.md

@@ -56,6 +56,33 @@ protected function mapApiRoutes()
 
 The middleware will authenticate API requests, ensuring they contain an API key that is valid.
 
+### Generating API keys
+
+You can generate new API keys by calling the `createApiKey()` method from the `Keyable` trait.
+
+When you do so, it returns an instance of `NewApiKey`, which is a simple class the contains the actual `ApiKey` instance that was just created, and also contains the plain text api key, which is the one you should use to authenticate requests.
+
+```php
+$newApiKey = $keyable->createApiKey();
+
+$newApiKey->plainTextApiKey // This is the key you should use to authenticate requests
+$newApiKey->apiKey // The instance of ApiKey just created
+```
+
+You can also manually create API keys without using the `createApiKey` from the `Keyable` trait, in that case, the instance you get back will have a property called `plainTextApikey` populated with the plain text API key.
+
+```php
+$myApiKey = ApiKey::create([
+    'keyable_id' => $account->getKey(),
+    'keyable_type' => Account::class,
+    'name' => 'My api key',
+]);
+
+$myApiKey->plainTextApikey // Token to be used to authenticate requests
+```
+
+Keep in mind `plainTextApikey` will only be populated immediately after creating the key.
+
 ### Accessing keyable models in your controllers
 The model associated with the key will be attached to the incoming request as ```keyable```:
 
@@ -263,14 +290,18 @@ Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
 Generate an API key:
 
 ```bash
-php artisan api-key:generate --id=1 --type="App\Models\Account"
+php artisan api-key:generate --id=1 --type="App\Models\Account" --name="My api key"
 ```
 
 Delete an API key:
 ```bash
 php artisan api-key:delete --id=12345
 ```
 
+## Upgrading
+
+Please see [UPGRADING](UPGRADING.md) for details.
+
 ## Security
 
 If you discover any security related issues, please email [liran@givebutter.com](mailto:liran@givebutter.com).

UPGRADING.md

@@ -0,0 +1,54 @@
+## Upgrade guide
+
+### From 2.1.1 to 3.0.0
+
+ATTENTION: It is highly recommended that you generate a backup of your database before going through the steps below, just to be safe in case something goes wrong.
+
+#### Step 1: `api_keys` table updates
+
+Implement the following changes on your `api_keys` table.
+
+- Add a new nullable string column called `name`.
+- Modify the existing `key` column to increase its length from 40 to 64.
+
+#### Step 2: Update the package to version 3.0.0
+
+```bash
+composer require givebutter/laravel-keyable:3.0.0
+```
+
+#### Step 3. Turn on `compatibility_mode`
+
+A new configuration flag was introduced in the `keyable.php` config file on version `3.0.0`, it is called `compatibility_mode`, make sure to publish the package's config file to be able to access it.
+
+By default it is set to `false`, but when it is set to `true` the package will handle both hashed and non hashed API keys, which should keep your application running smoothly while you complete all upgrade steps.
+
+It is specially useful if you have a very large `api_keys` table, which could take a while to hash all existing API keys.
+
+It points to an environment variable called `KEYABLE_COMPATIBILITY_MODE`, but you can update it to whatever you need of course.
+
+Make sure to update `KEYABLE_COMPATIBILITY_MODE` to `true` if you want to make use of that feature.
+
+#### Step 4. Hash existing API keys
+
+A command was added to hash existing API keys that are not currently hashed, it will ensure existing API keys will continue working properly once you finish all upgrade steps.
+
+```bash
+php artisan api-key:hash
+```
+
+It is also possible to hash a single API key at a time, by passing an `--id` option.
+
+```bash
+php artisan api-key:hash --id=API_KEY_ID
+```
+
+Be very careful with this option, as each API key should be hashed only once.
+
+Ideally you should only use it for testing and on your own API keys.
+
+The command tries to avoid hashing an API key twice by comparing the length of the `key` column, if it is already 64 then the command understands the key is already hashed and won't do it again.
+
+#### Step 5. Turn off compatibility mode
+
+If you are making use of the compatibility mode, it can now be turned off by setting `KEYABLE_COMPATIBILITY_MODE` to `false`, it is not needed anymore.

composer.json

@@ -21,7 +21,8 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "require": {
-	    "php": "^7.0|^8.0"
+        "php": "^7.0|^8.0",
+        "doctrine/dbal": "^3.7"
     },
     "autoload": {
         "psr-4": {

config/keyable.php

@@ -28,4 +28,25 @@
 
     'allow_empty_models' => false,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Compatibility mode
+    |--------------------------------------------------------------------------
+    |
+    | Set this to true to instruct this package to accept both hashed and non
+    | hashed API keys.
+    |
+    | This is useful to keep your app running smoothly while you are going
+    | throught the upgrade steps for version 2.1.1 to 3.0.0, especially if you
+    | have a very large api_keys table, which can take a while to hash all
+    | existing API keys.
+    |
+    | Once the new database changes are in place and all existing keys are
+    | hashed, you should set this flag to false to instruct this package to
+    | only look for hashed API keys.
+    |
+    */
+
+    'compatibility_mode' => env('KEYABLE_COMPATIBILITY_MODE', false),
+
 ];

database/migrations/2019_04_09_225232_create_api_keys_table.php

@@ -16,7 +16,8 @@ public function up()
         Schema::create('api_keys', function (Blueprint $table) {
             $table->increments('id');
             $table->nullableMorphs('keyable');
-            $table->string('key', 40);
+            $table->string('name')->nullable();
+            $table->string('key', 64);
             $table->dateTime('last_used_at')->nullable();
             $table->timestamps();
             $table->softDeletes();

src/Console/Commands/GenerateApiKey.php

@@ -14,7 +14,8 @@ class GenerateApiKey extends Command
      */
     protected $signature = 'api-key:generate
                             {--id= : ID of the model you want to bind to this API key}
-                            {--type= : The class name of the model you want to bind to this API key}';
+                            {--type= : The class name of the model you want to bind to this API key}
+                            {--name= : The name you want to give to this API key}';
 
     /**
      * The console command description.
@@ -41,8 +42,9 @@ public function handle()
         $apiKey = (new ApiKey)->create([
             'keyable_id' => $this->option('id'),
             'keyable_type' => $this->option('type'),
+            'name' => $this->option('name'),
         ]);
 
-        $this->info('The following API key was created: ' . $apiKey->key);
+        $this->info('The following API key was created: ' . "{$apiKey->getKey()}|{$apiKey->plainTextApiKey}");
     }
 }

src/Console/Commands/HashApiKeys.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Givebutter\LaravelKeyable\Console\Commands;
+
+use Givebutter\LaravelKeyable\Models\ApiKey;
+use Illuminate\Console\Command;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Facades\DB;
+
+class HashApiKeys extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'api-key:hash {--id= : ID of the API key you want to hash}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Hash existing API keys';
+
+    /**
+     * Execute the console command.
+     *
+     * @return mixed
+     */
+    public function handle()
+    {
+        DB::transaction(function () {
+            ApiKey::query()
+                ->withTrashed()
+                ->when($this->option('id'), function (Builder $query, int $id) {
+                    $query->where('id', $id);
+                })
+                ->whereRaw('LENGTH(api_keys.key) != 64')
+                ->eachById(function (ApiKey $apiKey) {
+                    $apiKey->update([
+                        'key' => hash('sha256', $apiKey->key),
+                    ]);
+
+                    $this->info("API key #{$apiKey->getKey()} successfully hashed.");
+                }, 250);
+
+            $this->info('All API keys were successfully hashed.');
+        });
+    }
+}

src/Keyable.php

@@ -3,6 +3,7 @@
 namespace Givebutter\LaravelKeyable;
 
 use Givebutter\LaravelKeyable\Models\ApiKey;
+use Illuminate\Database\Eloquent\Model;
 
 trait Keyable
 {
@@ -11,8 +12,17 @@ public function apiKeys()
         return $this->morphMany(ApiKey::class, 'keyable');
     }
 
-    public function createApiKey()
+    public function createApiKey(array $attributes = []): NewApiKey
     {
-        return $this->apiKeys()->create([]);
+        $planTextApiKey = ApiKey::generate();
+
+        $apiKey = Model::withoutEvents(function () use ($planTextApiKey, $attributes) {
+            return $this->apiKeys()->create([
+                'key' => hash('sha256', $planTextApiKey),
+                'name' => $attributes['name'] ?? null,
+            ]);
+        });
+
+        return new NewApiKey($apiKey, "{$apiKey->getKey()}|{$planTextApiKey}");
     }
 }

src/KeyableServiceProvider.php

@@ -8,6 +8,7 @@
 use Illuminate\Routing\PendingResourceRegistration;
 use Givebutter\LaravelKeyable\Console\Commands\DeleteApiKey;
 use Givebutter\LaravelKeyable\Console\Commands\GenerateApiKey;
+use Givebutter\LaravelKeyable\Console\Commands\HashApiKeys;
 use Givebutter\LaravelKeyable\Http\Middleware\AuthenticateApiKey;
 use Givebutter\LaravelKeyable\Http\Middleware\EnforceKeyableScope;
 
@@ -49,6 +50,7 @@ protected function registerCommands()
             $this->commands([
                 GenerateApiKey::class,
                 DeleteApiKey::class,
+                HashApiKeys::class,
             ]);
         }
     }

src/Models/ApiKey.php

@@ -2,6 +2,7 @@
 
 namespace Givebutter\LaravelKeyable\Models;
 
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Support\Str;
@@ -10,25 +11,31 @@ class ApiKey extends Model
 {
     use SoftDeletes;
 
+    public ?string $plainTextApiKey = null;
+
     protected $table = 'api_keys';
 
     protected $fillable = [
-        'key', 
-        'keyable_id', 
-        'keyable_type', 
+        'key',
+        'keyable_id',
+        'keyable_type',
+        'name',
         'last_used_at',
     ];
 
     protected $casts = [
         'last_used_at' => 'datetime',
     ];
-    
+
     public static function boot()
     {
         parent::boot();
 
-        static::creating(function ($apiKey) {
-            $apiKey->key = self::generate();
+        static::creating(function (ApiKey $apiKey) {
+            if (is_null($apiKey->key)) {
+                $apiKey->plainTextApiKey = self::generate();
+                $apiKey->key = hash('sha256', $apiKey->plainTextApiKey);
+            }
         });
     }
 
@@ -63,7 +70,7 @@ public static function generate()
      */
     public static function getByKey($key)
     {
-        return self::where('key', $key)->first();
+        return self::ofKey($key)->first();
     }
 
     /**
@@ -77,7 +84,7 @@ public static function getByKey($key)
      */
     public static function keyExists($key)
     {
-        return self::where('key', $key)
+        return self::ofKey($key)
             ->withTrashed()
             ->first() instanceof self;
     }
@@ -91,4 +98,24 @@ public function markAsUsed()
             'last_used_at' => $this->freshTimestamp()
         ])->save();
     }
+
+    public function scopeOfKey(Builder $query, string $key): Builder
+    {
+        $compatibilityMode = config('keyable.compatibility_mode', false);
+
+        if ($compatibilityMode) {
+            return $query->where(function (Builder $query) use ($key) {
+                return $query->where('key', $key)
+                    ->orWhere('key', hash('sha256', $key));
+            });
+        }
+
+        if (strpos($key, '|') === false) {
+            return $query->where('key', hash('sha256', $key));
+        }
+
+        [$id, $key] = explode('|', $key, 2);
+
+        return $query->where('id', $id)->where('key', hash('sha256', $key));
+    }
 }