From 60a786b539402ef532ddc6c7f88203eaa88e4547 Mon Sep 17 00:00:00 2001
From: Pierre-Yves Chibon <pingou@pingoured.fr>
Date: Mar 23 2017 10:43:29 +0000
Subject: Add a description to the API token


This will allow users to document the usage of the API token so they know
which is used for what.

Fixes https://pagure.io/pagure/issue/2115

---

diff --git a/alembic/versions/3ffec872dfdf_add_a_description_to_api_token.py b/alembic/versions/3ffec872dfdf_add_a_description_to_api_token.py
new file mode 100644
index 0000000..2fddac7
--- /dev/null
+++ b/alembic/versions/3ffec872dfdf_add_a_description_to_api_token.py
@@ -0,0 +1,29 @@
+"""Add a description to api token
+
+Revision ID: 3ffec872dfdf
+Revises: 770149d96e24
+Create Date: 2017-03-23 11:30:34.827399
+
+"""
+
+# revision identifiers, used by Alembic.
+revision = '3ffec872dfdf'
+down_revision = '770149d96e24'
+
+from alembic import op
+import sqlalchemy as sa
+
+
+def upgrade():
+    ''' Add the column description to the table tokens
+    '''
+    op.add_column(
+        'tokens',
+        sa.Column('description', sa.Text, nullable=True)
+    )
+
+
+def downgrade():
+    ''' Drop the column description from the table tokens.
+    '''
+    op.drop_column('tokens', 'description')
diff --git a/pagure/forms.py b/pagure/forms.py
index d6edf53..9e91727 100644
--- a/pagure/forms.py
+++ b/pagure/forms.py
@@ -288,6 +288,9 @@ class StatusForm(PagureForm):
 
 class NewTokenForm(PagureForm):
     ''' Form to add/change the status of an issue. '''
+    description = wtforms.TextField(
+        'description', [wtforms.validators.Optional()]
+    )
     acls = wtforms.SelectMultipleField(
         'ACLs',
         [wtforms.validators.Required()],
diff --git a/pagure/lib/__init__.py b/pagure/lib/__init__.py
index 43ad605..4138ea5 100644
--- a/pagure/lib/__init__.py
+++ b/pagure/lib/__init__.py
@@ -3272,7 +3272,7 @@ def get_acls(session, restrict=None):
     return query.all()
 
 
-def add_token_to_user(session, project, acls, username):
+def add_token_to_user(session, project, acls, username, description=None):
     """ Create a new token for the specified user on the specified project
     with the given ACLs.
     """
@@ -3288,6 +3288,7 @@ def add_token_to_user(session, project, acls, username):
         id=pagure.lib.login.id_generator(64),
         user_id=user.id,
         project_id=project.id if project else None,
+        description=description,
         expiration=datetime.datetime.utcnow() + datetime.timedelta(days=60)
     )
     session.add(token)
diff --git a/pagure/lib/model.py b/pagure/lib/model.py
index 3651f0e..6657d56 100644
--- a/pagure/lib/model.py
+++ b/pagure/lib/model.py
@@ -2171,6 +2171,7 @@ class Token(BASE):
         ),
         nullable=True,
         index=True)
+    description = sa.Column(sa.Text(), nullable=True)
     expiration = sa.Column(
         sa.DateTime, nullable=False, default=datetime.datetime.utcnow)
     created = sa.Column(
diff --git a/pagure/templates/add_token.html b/pagure/templates/add_token.html
index a9f6b53..8d6b0d7 100644
--- a/pagure/templates/add_token.html
+++ b/pagure/templates/add_token.html
@@ -3,7 +3,7 @@
 {% else %}
 {% extends "master.html" %}
 {% endif %}
-{% from "_formhelper.html" import render_field_in_row %}
+{% from "_formhelper.html" import render_bootstrap_field %}
 
 {% set tag = "home" %}
 {% block title %}Create token{% endblock %}
@@ -33,16 +33,18 @@
           {% else %}
           <form action="{{ url_for('.add_api_user_token') }}" method="post">
           {% endif %}
-            {% for acl in acls %}
-            <div>
-              <label class="c-input c-checkbox">
-                <input type="checkbox" name="acls" value="{{ acl.name }}">
-                <span class="c-indicator"></span>
-                {{ acl.description }}
-              </label>
-            </div>
-            {% endfor %}
-          </table>
+          {{ render_bootstrap_field(
+              form.description, field_description="Small description of this API token") }}
+          <strong><label for="acls">ACLs</label></strong>
+          {% for acl in acls %}
+          <div>
+            <label class="c-input c-checkbox">
+              <input type="checkbox" name="acls" value="{{ acl.name }}">
+              <span class="c-indicator"></span>
+              {{ acl.description }}
+            </label>
+          </div>
+          {% endfor %}
           <div class="p-t-2">
             <input type="submit" class="btn btn-primary" value="Create">
             {% if repo %}
diff --git a/pagure/templates/settings.html b/pagure/templates/settings.html
index c76401c..80f9dc3 100644
--- a/pagure/templates/settings.html
+++ b/pagure/templates/settings.html
@@ -137,7 +137,12 @@
             <li class="list-group-item">
               <div class="form-group">
                 <div class="input-group">
-                  <div class="input-group-addon"><span class="oi" data-glyph="key"></span></div>
+                  <strong>{{ token.description or '' }}</strong>
+                </div>
+                <div class="input-group">
+                  <div class="input-group-addon">
+                    <span class="oi" data-glyph="key"></span>
+                  </div>
                   <input class="form-control" type="text" value="{{ token.id }}" readonly>
                 </div>
               </div>
diff --git a/pagure/ui/app.py b/pagure/ui/app.py
index b2a0ab5..a21f273 100644
--- a/pagure/ui/app.py
+++ b/pagure/ui/app.py
@@ -786,6 +786,7 @@ def add_api_user_token():
             msg = pagure.lib.add_token_to_user(
                 SESSION,
                 project=None,
+                description=form.description.data.strip() or None,
                 acls=form.acls.data,
                 username=flask.g.fas_user.username,
             )
diff --git a/pagure/ui/repo.py b/pagure/ui/repo.py
index f3b2cfa..9b75f4c 100644
--- a/pagure/ui/repo.py
+++ b/pagure/ui/repo.py
@@ -2033,6 +2033,7 @@ def add_token(repo, username=None, namespace=None):
             msg = pagure.lib.add_token_to_user(
                 SESSION,
                 repo,
+                description=form.description.data.strip() or None,
                 acls=form.acls.data,
                 username=flask.g.fas_user.username,
             )
diff --git a/tests/test_pagure_flask_ui_repo.py b/tests/test_pagure_flask_ui_repo.py
index dbd3bc8..21d7817 100644
--- a/tests/test_pagure_flask_ui_repo.py
+++ b/tests/test_pagure_flask_ui_repo.py
@@ -3846,7 +3846,11 @@ index 0000000..fb7093d
                     '</button>\n                      You must select at least '
                     'one permission.', output.data)
 
-            data = {'csrf_token': csrf_token, 'acls': ['issue_create']}
+            data = {
+                'csrf_token': csrf_token,
+                'acls': ['issue_create'],
+                'description': 'Test token',
+            }
 
             # New token created
             data = {'csrf_token': csrf_token, 'acls': ['issue_create']}
@@ -3858,6 +3862,7 @@ index 0000000..fb7093d
             self.assertIn(
                 '<title>Settings - test - Pagure</title>', output.data)
             self.assertIn('<h3>Settings for test</h3>', output.data)
+            self.assertIn('<strong>Test token</strong>', output.data)
             self.assertIn(
                 '<span class="text-success btn-align"><strong>Valid</strong> until: ',
                 output.data)