From 9494991176ba67f64da63fd9d8bdfa85612e3dff Mon Sep 17 00:00:00 2001
From: Seth Vargo <seth@sethvargo.com>
Date: Wed, 16 Dec 2020 20:45:07 -0500
Subject: [PATCH] Add API key type for accessing statistics

---
 cmd/server/assets/apikeys/index.html |   3 +-
 cmd/server/assets/apikeys/new.html   |  17 +--
 cmd/server/assets/apikeys/show.html  | 216 ++++++++++++++-------------
 docs/api.md                          |  18 ++-
 internal/routes/adminapi.go          |  33 ++--
 pkg/controller/apikey/create.go      |   1 +
 pkg/controller/middleware/apikey.go  |   2 +-
 pkg/database/authorized_app.go       |   9 +-
 pkg/database/authorized_app_test.go  |   2 +
 tools/seed/main.go                   |   6 +-
 10 files changed, 165 insertions(+), 142 deletions(-)

diff --git a/cmd/server/assets/apikeys/index.html b/cmd/server/assets/apikeys/index.html
index dd2d8c19a..313835523 100644
--- a/cmd/server/assets/apikeys/index.html
+++ b/cmd/server/assets/apikeys/index.html
@@ -75,8 +75,9 @@
                 {{.APIKeyPreview}}
               </td>
               <td class="text-center">
-                {{if .IsAdminType}}<span class="badge badge-pill badge-primary" data-toggle="tooltip" title="Can be used to issue verification codes">Admin</span>{{end}}
+                {{if .IsAdminType}}<span class="badge badge-pill badge-primary" data-toggle="tooltip" title="For issuing verification codes">Admin</span>{{end}}
                 {{if .IsDeviceType}}<span class="badge badge-pill badge-secondary" data-toggle="tooltip" title="For use in mobile apps to verify codes and get certificates">Device</span>{{end}}
+                {{if .IsStatsType}}<span class="badge badge-pill badge-secondary" data-toggle="tooltip" title="For retrieving realm statistics">Stats</span>{{end}}
               </td>
               {{if $canWrite}}
                 <td class="text-center">
diff --git a/cmd/server/assets/apikeys/new.html b/cmd/server/assets/apikeys/new.html
index 994b846fc..daa5bf101 100644
--- a/cmd/server/assets/apikeys/new.html
+++ b/cmd/server/assets/apikeys/new.html
@@ -28,25 +28,18 @@ <h1>New API key</h1>
           <div class="form-label-group">
             <input type="text" id="name" name="name" class="form-control{{if $authApp.ErrorsFor "name"}} is-invalid{{end}}" value="{{$authApp.Name}}" placeholder="Application name" autofocus>
             <label for="name">Application name</label>
-            {{if $authApp.ErrorsFor "name"}}
-            <div class="invalid-feedback">
-              {{joinStrings ($authApp.ErrorsFor "name") ", "}}
-            </div>
-            {{end}}
+            {{template "errorable" $authApp.ErrorsFor "name"}}
           </div>
 
           <div class="form-group">
             <input type="hidden" name="type" value="-1">
             <select class="form-control{{if $authApp.ErrorsFor "type"}} is-invalid{{end}}" name="type" id="type">
               <option selected disabled>Select type...</option>
-              <option value="{{.typeDevice}}" {{if (eq $authApp.APIKeyType .typeDevice)}}selected{{end}}>Device (can verify codes)</option>
-              <option value="{{.typeAdmin}}" {{if (eq $authApp.APIKeyType .typeAdmin)}}selected{{end}}>Admin (can issue codes)</option>
+              <option value="{{.typeDevice}}" {{selectedIf (eq $authApp.APIKeyType .typeDevice)}}>Device (can verify codes)</option>
+              <option value="{{.typeAdmin}}" {{selectedIf (eq $authApp.APIKeyType .typeAdmin)}}>Admin (can issue codes)</option>
+              <option value="{{.typeStats}}" {{selectedIf (eq $authApp.APIKeyType .typeStats)}}>Stats (can view statistics)</option>
             </select>
-            {{if $authApp.ErrorsFor "type"}}
-            <div class="invalid-feedback">
-              {{joinStrings ($authApp.ErrorsFor "type") ", "}}
-            </div>
-            {{end}}
+            {{template "errorable" $authApp.ErrorsFor "type"}}
           </div>
 
           <button type="submit" id="submit" class="btn btn-primary btn-block">Create API key</button>
diff --git a/cmd/server/assets/apikeys/show.html b/cmd/server/assets/apikeys/show.html
index f9a9452db..e1a597ed0 100644
--- a/cmd/server/assets/apikeys/show.html
+++ b/cmd/server/assets/apikeys/show.html
@@ -26,17 +26,17 @@ <h1>{{$authApp.Name}} API key</h1>
     </p>
 
     {{if $apiKey}}
-    <div class="card mb-3 shadow-sm">
-      <div class="card-header">API key</div>
-      <div class="card-body">
-        <div class="alert alert-danger" role="alert">
-          This is your API key - it will only be displayed once. <strong>You
-            must securely save this API key elsewhere!</strong>
-        </div>
+      <div class="card mb-3 shadow-sm">
+        <div class="card-header">API key</div>
+        <div class="card-body">
+          <div class="alert alert-danger" role="alert">
+            This is your API key - it will only be displayed once. <strong>You
+              must securely save this API key elsewhere!</strong>
+          </div>
 
-        <textarea id="apikey-value" class="form-control" rows="4" readonly>{{$apiKey}}</textarea>
+          <textarea id="apikey-value" class="form-control" rows="4" readonly>{{$apiKey}}</textarea>
+        </div>
       </div>
-    </div>
     {{end}}
 
     <div class="card mb-3 shadow-sm">
@@ -61,6 +61,8 @@ <h1>{{$authApp.Name}} API key</h1>
             Device (can verify codes)
           {{else if $authApp.IsAdminType}}
             Admin (can issue codes)
+          {{else if $authApp.IsStatsType}}
+            Stats (can view stats)
           {{else}}
             Unknown
           {{end}}
@@ -68,111 +70,113 @@ <h1>{{$authApp.Name}} API key</h1>
       </div>
     </div>
 
-    <div class="card mb-3 shadow-sm">
-      <div class="card-header">
-        <span class="oi oi-bar-chart mr-2 ml-n1"></span>
-        Statistics
-      </div>
-      <div class="card-body">
-        <div id="apikey_stats_chart" class="container d-flex h-100 w-100" style="min-height:300px;">
-          <p class="justify-content-center align-self-center text-center font-italic w-100">Loading chart...</p>
+    {{if $authApp.IsAdminType}}
+      <div class="card mb-3 shadow-sm">
+        <div class="card-header">
+          <span class="oi oi-bar-chart mr-2 ml-n1"></span>
+          Statistics
         </div>
+        <div class="card-body">
+          <div id="apikey_stats_chart" class="container d-flex h-100 w-100" style="min-height:300px;">
+            <p class="justify-content-center align-self-center text-center font-italic w-100">Loading chart...</p>
+          </div>
+        </div>
+        <small class="card-footer d-flex justify-content-between text-muted">
+          <span>
+            This data is refreshed every 30 minutes.
+            <a href="#" data-toggle="modal" data-target="#apikey-stats-modal">Learn more</a>
+          </span>
+          <span>
+            <span class="mr-1">Export as:</span>
+            <a href="/realm/apikeys/{{$authApp.ID}}/stats.csv" class="mr-1">CSV</a>
+            <a href="/realm/apikeys/{{$authApp.ID}}/stats.json">JSON</a>
+          </span>
+        </small>
       </div>
-      <small class="card-footer d-flex justify-content-between text-muted">
-        <span>
-          This data is refreshed every 30 minutes.
-          <a href="#" data-toggle="modal" data-target="#apikey-stats-modal">Learn more</a>
-        </span>
-        <span>
-          <span class="mr-1">Export as:</span>
-          <a href="/realm/apikeys/{{$authApp.ID}}/stats.csv" class="mr-1">CSV</a>
-          <a href="/realm/apikeys/{{$authApp.ID}}/stats.json">JSON</a>
-        </span>
-      </small>
-    </div>
 
-    <div class="modal fade" id="apikey-stats-modal" data-backdrop="static" tabindex="-1" aria-hidden="true">
-      <div class="modal-dialog modal-dialog-centered">
-        <div class="modal-content">
-          <div class="modal-header">
-            <h5 class="modal-title">Codes issued by {{$authApp.Name}}</h5>
-            <button type="button" class="close" data-dismiss="modal" aria-label="Close">
-              <span aria-hidden="true">&times;</span>
-            </button>
-          </div>
-          <div class="modal-body mb-n3">
-            <p>
-              This chart reflects the number of codes issued by
-              {{$authApp.Name}}.
-            </p>
-            <p>
-              This chart does <u>not</u> include codes that were issued by users
-              via the UI or codes that were issued using a different API key.
-            </p>
+      <div class="modal fade" id="apikey-stats-modal" data-backdrop="static" tabindex="-1" aria-hidden="true">
+        <div class="modal-dialog modal-dialog-centered">
+          <div class="modal-content">
+            <div class="modal-header">
+              <h5 class="modal-title">Codes issued by {{$authApp.Name}}</h5>
+              <button type="button" class="close" data-dismiss="modal" aria-label="Close">
+                <span aria-hidden="true">&times;</span>
+              </button>
+            </div>
+            <div class="modal-body mb-n3">
+              <p>
+                This chart reflects the number of codes issued by
+                {{$authApp.Name}}.
+              </p>
+              <p>
+                This chart does <u>not</u> include codes that were issued by users
+                via the UI or codes that were issued using a different API key.
+              </p>
+            </div>
           </div>
         </div>
       </div>
-    </div>
-  </main>
-
-  <script src="https://www.gstatic.com/charts/loader.js"></script>
-  <script>
-    let userStatsChartDiv = document.getElementById('apikey_stats_chart');
-    let dateFormatter;
-
-    google.charts.load('current', {
-      packages: ['corechart'],
-      callback: function() {
-        dateFormatter = new google.visualization.DateFormat({
-          pattern: 'MMM dd',
-        });
+    </main>
+
+    <script src="https://www.gstatic.com/charts/loader.js"></script>
+    <script>
+      let userStatsChartDiv = document.getElementById('apikey_stats_chart');
+      let dateFormatter;
+
+      google.charts.load('current', {
+        packages: ['corechart'],
+        callback: function() {
+          dateFormatter = new google.visualization.DateFormat({
+            pattern: 'MMM dd',
+          });
+
+          drawStats();
+        },
+      });
 
-        drawStats();
-      },
-    });
-
-    function drawStats() {
-      $.ajax({
-        url: '/realm/apikeys/{{$authApp.ID}}/stats.json',
-        dataType: 'json',
-      })
-      .done(function(data, status, xhr) {
-        if (!data.statistics) {
-          $(userStatsChartDiv).find('p').text('This API key has not yet issued any codes.');
-          return;
-        }
-
-        var dataTable = new google.visualization.DataTable();
-        dataTable.addColumn('date', 'Date');
-        dataTable.addColumn('number', 'Issued');
-
-        data.statistics.reverse().forEach(function(row) {
-          dataTable.addRow([utcDate(row.date), row.data.codes_issued]);
+      function drawStats() {
+        $.ajax({
+          url: '/realm/apikeys/{{$authApp.ID}}/stats.json',
+          dataType: 'json',
+        })
+        .done(function(data, status, xhr) {
+          if (!data.statistics) {
+            $(userStatsChartDiv).find('p').text('This API key has not yet issued any codes.');
+            return;
+          }
+
+          var dataTable = new google.visualization.DataTable();
+          dataTable.addColumn('date', 'Date');
+          dataTable.addColumn('number', 'Issued');
+
+          data.statistics.reverse().forEach(function(row) {
+            dataTable.addRow([utcDate(row.date), row.data.codes_issued]);
+          });
+
+          dateFormatter.format(dataTable, 0);
+
+          let options = {
+            colors: ['#007bff'],
+            chartArea: {
+              left: 60, // leave room for y-axis labels
+              top: 20,
+              bottom: 20,
+              width: '100%',
+              height: '100%',
+            },
+            hAxis: { format: 'M/d' },
+            legend: 'none',
+          };
+
+          let chart = new google.visualization.LineChart(userStatsChartDiv);
+          chart.draw(dataTable, options);
+        })
+        .fail(function(xhr, status, err) {
+          flash.error('Failed to render API key stats: ' + err);
         });
-
-        dateFormatter.format(dataTable, 0);
-
-        let options = {
-          colors: ['#007bff'],
-          chartArea: {
-            left: 60, // leave room for y-axis labels
-            top: 20,
-            bottom: 20,
-            width: '100%',
-            height: '100%',
-          },
-          hAxis: { format: 'M/d' },
-          legend: 'none',
-        };
-
-        let chart = new google.visualization.LineChart(userStatsChartDiv);
-        chart.draw(dataTable, options);
-      })
-      .fail(function(xhr, status, err) {
-        flash.error('Failed to render API key stats: ' + err);
-      });
-    }
-  </script>
+      }
+    </script>
+  {{end}}
 </body>
 
 </html>
diff --git a/docs/api.md b/docs/api.md
index f21fb98ae..be898802d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,3 +1,5 @@
+<!-- TOC depthFrom:1 -->
+
 - [API access](#api-access)
 - [API usage](#api-usage)
   - [Authenticating](#authenticating)
@@ -5,16 +7,14 @@
 - [API Methods](#api-methods)
   - [`/api/verify`](#apiverify)
   - [`/api/certificate`](#apicertificate)
-- [Admin APIs](#admin-apis)
-  - [`/api/issue`](#apiissue)
-    - [Client provided UUID to prevent duplicate SMS](#client-provided-uuid-to-prevent-duplicate-sms)
-  - [`/api/batch-issue`](#apibatch-issue)
-    - [Handling batch partial success/failure](#handling-batch-partial-successfailure)
   - [`/api/checkcodestatus`](#apicheckcodestatus)
   - [`/api/expirecode`](#apiexpirecode)
+  - [`/api/stats/*` (preview)](#apistats-preview)
 - [Chaffing requests](#chaffing-requests)
 - [Response codes overview](#response-codes-overview)
 
+<!-- /TOC -->
+
 # API access
 
 Access to the verification server API requires an API key. An API key typically
@@ -27,8 +27,12 @@ two types of API keys:
     _certificates_.
 
 -   `ADMIN` - Intended for public health authority internal applications to
-    integrate with this server. **We strongly advise putting additional
-    protections in place such as an external proxy authentication.**
+    integrate with this server. This API key type can also retrieve statistics
+    about the realm. **We strongly advise putting additional protections in
+    place such as an external proxy authentication.**
+
+-   `STATS` - Intended for public health authorities to gather automated
+    statistics.
 
 
 # API usage
diff --git a/internal/routes/adminapi.go b/internal/routes/adminapi.go
index 977f645c9..56ccc0484 100644
--- a/internal/routes/adminapi.go
+++ b/internal/routes/adminapi.go
@@ -86,9 +86,13 @@ func AdminAPI(
 	r.Use(rateLimit)
 
 	// Other common middlewares
-	requireAPIKey := middleware.RequireAPIKey(cacher, db, h, []database.APIKeyType{
+	requireAdminAPIKey := middleware.RequireAPIKey(cacher, db, h, []database.APIKeyType{
 		database.APIKeyTypeAdmin,
 	})
+	requireStatsAPIKey := middleware.RequireAPIKey(cacher, db, h, []database.APIKeyType{
+		database.APIKeyTypeAdmin,
+		database.APIKeyTypeStats,
+	})
 	processFirewall := middleware.ProcessFirewall(h, "adminapi")
 
 	// Health route
@@ -97,7 +101,7 @@ func AdminAPI(
 	// API routes
 	{
 		sub := r.PathPrefix("/api").Subrouter()
-		sub.Use(requireAPIKey)
+		sub.Use(requireAdminAPIKey)
 		sub.Use(processFirewall)
 
 		issueapiController := issueapi.New(ctx, cfg, db, limiterStore, h)
@@ -107,18 +111,21 @@ func AdminAPI(
 		codesController := codes.NewAPI(ctx, cfg, db, h)
 		sub.Handle("/checkcodestatus", codesController.HandleCheckCodeStatus()).Methods("POST")
 		sub.Handle("/expirecode", codesController.HandleExpireAPI()).Methods("POST")
+	}
+
+	// Stats routes
+	{
+		sub := r.PathPrefix("/api/stats").Subrouter()
+		sub.Use(requireStatsAPIKey)
+		sub.Use(processFirewall)
 
-		{
-			sub := sub.PathPrefix("/stats").Subrouter()
-
-			statsController := stats.New(ctx, cacher, db, h)
-			sub.Handle("/realm.csv", statsController.HandleRealmStats(stats.StatsTypeCSV)).Methods("GET")
-			sub.Handle("/realm.json", statsController.HandleRealmStats(stats.StatsTypeJSON)).Methods("GET")
-			sub.Handle("/realm-user.csv", statsController.HandleRealmUserStats(stats.StatsTypeCSV)).Methods("GET")
-			sub.Handle("/realm-user.json", statsController.HandleRealmUserStats(stats.StatsTypeJSON)).Methods("GET")
-			sub.Handle("/realm-external-issuer.csv", statsController.HandleRealmExternalIssuerStats(stats.StatsTypeCSV)).Methods("GET")
-			sub.Handle("/realm-external-issuer.json", statsController.HandleRealmExternalIssuerStats(stats.StatsTypeJSON)).Methods("GET")
-		}
+		statsController := stats.New(ctx, cacher, db, h)
+		sub.Handle("/realm.csv", statsController.HandleRealmStats(stats.StatsTypeCSV)).Methods("GET")
+		sub.Handle("/realm.json", statsController.HandleRealmStats(stats.StatsTypeJSON)).Methods("GET")
+		sub.Handle("/realm-user.csv", statsController.HandleRealmUserStats(stats.StatsTypeCSV)).Methods("GET")
+		sub.Handle("/realm-user.json", statsController.HandleRealmUserStats(stats.StatsTypeJSON)).Methods("GET")
+		sub.Handle("/realm-external-issuer.csv", statsController.HandleRealmExternalIssuerStats(stats.StatsTypeCSV)).Methods("GET")
+		sub.Handle("/realm-external-issuer.json", statsController.HandleRealmExternalIssuerStats(stats.StatsTypeJSON)).Methods("GET")
 	}
 
 	// Wrap the main router in the mutating middleware method. This cannot be
diff --git a/pkg/controller/apikey/create.go b/pkg/controller/apikey/create.go
index 2ef292d6d..51b1189c3 100644
--- a/pkg/controller/apikey/create.go
+++ b/pkg/controller/apikey/create.go
@@ -102,5 +102,6 @@ func (c *Controller) renderNew(ctx context.Context, w http.ResponseWriter, authA
 	m["authApp"] = authApp
 	m["typeAdmin"] = database.APIKeyTypeAdmin
 	m["typeDevice"] = database.APIKeyTypeDevice
+	m["typeStats"] = database.APIKeyTypeStats
 	c.h.RenderHTML(w, "apikeys/new", m)
 }
diff --git a/pkg/controller/middleware/apikey.go b/pkg/controller/middleware/apikey.go
index 7d9acbece..0fb3d7d24 100644
--- a/pkg/controller/middleware/apikey.go
+++ b/pkg/controller/middleware/apikey.go
@@ -42,7 +42,7 @@ func RequireAPIKey(cacher cache.Cacher, db *database.Database, h render.Renderer
 		allowedTypesMap[t] = struct{}{}
 	}
 
-	cacheTTL := 5 * time.Minute
+	cacheTTL := 30 * time.Minute
 
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
diff --git a/pkg/database/authorized_app.go b/pkg/database/authorized_app.go
index 1bb8c4e6f..cc5e03db3 100644
--- a/pkg/database/authorized_app.go
+++ b/pkg/database/authorized_app.go
@@ -40,6 +40,7 @@ const (
 	APIKeyTypeInvalid APIKeyType = iota - 1
 	APIKeyTypeDevice
 	APIKeyTypeAdmin
+	APIKeyTypeStats
 )
 
 func (a APIKeyType) Display() string {
@@ -48,6 +49,8 @@ func (a APIKeyType) Display() string {
 		return "device"
 	case APIKeyTypeAdmin:
 		return "admin"
+	case APIKeyTypeStats:
+		return "stats"
 	default:
 		return "invalid"
 	}
@@ -91,7 +94,7 @@ func (a *AuthorizedApp) BeforeSave(tx *gorm.DB) error {
 		a.AddError("name", "cannot be blank")
 	}
 
-	if !(a.APIKeyType == APIKeyTypeDevice || a.APIKeyType == APIKeyTypeAdmin) {
+	if !(a.APIKeyType == APIKeyTypeDevice || a.APIKeyType == APIKeyTypeAdmin || a.APIKeyType == APIKeyTypeStats) {
 		a.AddError("type", "is invalid")
 	}
 
@@ -109,6 +112,10 @@ func (a *AuthorizedApp) IsDeviceType() bool {
 	return a.APIKeyType == APIKeyTypeDevice
 }
 
+func (a *AuthorizedApp) IsStatsType() bool {
+	return a.APIKeyType == APIKeyTypeStats
+}
+
 // Realm returns the associated realm for this app. If you only need the ID,
 // call .RealmID instead of a full database lookup.
 func (a *AuthorizedApp) Realm(db *Database) (*Realm, error) {
diff --git a/pkg/database/authorized_app_test.go b/pkg/database/authorized_app_test.go
index 16a3688d8..ce1c5efde 100644
--- a/pkg/database/authorized_app_test.go
+++ b/pkg/database/authorized_app_test.go
@@ -37,6 +37,7 @@ func TestAPIKeyType(t *testing.T) {
 		{APIKeyTypeInvalid, -1},
 		{APIKeyTypeDevice, 0},
 		{APIKeyTypeAdmin, 1},
+		{APIKeyTypeStats, 2},
 	}
 
 	for _, tc := range cases {
@@ -62,6 +63,7 @@ func TestAPIKeyType_Display(t *testing.T) {
 		{APIKeyTypeInvalid, "invalid"},
 		{APIKeyTypeDevice, "device"},
 		{APIKeyTypeAdmin, "admin"},
+		{APIKeyTypeStats, "stats"},
 		{1991, "invalid"},
 	}
 
diff --git a/tools/seed/main.go b/tools/seed/main.go
index 66cc5f9ca..f412b1212 100644
--- a/tools/seed/main.go
+++ b/tools/seed/main.go
@@ -229,6 +229,10 @@ func realMain(ctx context.Context) error {
 		return fmt.Errorf("failed to create admin api key: %w", err)
 	}
 	logger.Infow("created device api key", "key", adminAPIKey)
+	adminAuthorizedApp, err := db.FindAuthorizedAppByAPIKey(adminAPIKey)
+	if err != nil {
+		return fmt.Errorf("failed to lookup admin api id: %w", err)
+	}
 
 	// Generate some codes
 	now := time.Now().UTC()
@@ -253,7 +257,7 @@ func realMain(ctx context.Context) error {
 
 			// Random determine if this was issued by an app (60% chance).
 			if rand.Intn(10) <= 6 {
-				issuingAppID = apps[rand.Intn(len(apps))].ID
+				issuingAppID = adminAuthorizedApp.ID
 
 				// Random determine if the code had an external audit.
 				if rand.Intn(2) == 0 {