URLs: Document JSON API Passphrase Usage (#2118)

app/controllers/urls_controller.rb

@@ -20,7 +20,8 @@ class UrlsController < BaseController
   formats ["json"]
   example 'curl -X GET -H "X-User-Email: <email>" -H "X-User-Token: MyAPIToken" https://pwpush.com/r/fk27vnslkd.json'
   description "Retrieves a push including it's payload and details.  If the push is still active, " \
-              "this will burn a view and the transaction will be logged in the push audit log."
+              "this will burn a view and the transaction will be logged in the push audit log.  If the push " \
+              "has a passphrase, provide it in a ?passphrase=xxx GET parameter."
   def show
     # This url may have expired since the last view.  Validate the url
     # expiration before doing anything.

test/integration/url/url_json_retrieval_test.rb

@@ -14,6 +14,29 @@ class UrlJsonRetrievalTest < ActionDispatch::IntegrationTest
     @luca.confirm
   end
 
+  def test_view_with_passphrase
+    post urls_path(format: :json), params: {url: {payload: "https://the0x00.dev", expire_after_views: 2, passphrase: "asdf"}}, headers: {"X-User-Email": @luca.email, "X-User-Token": @luca.authentication_token}
+    assert_response :success
+
+    res = JSON.parse(@response.body)
+    url_token = res["url_token"]
+
+    # Now try to retrieve the url without the passphrase
+    get "/r/#{url_token}.json", headers: {"X-User-Email": @luca.email, "X-User-Token": @luca.authentication_token}
+    assert_response :success
+
+    res = JSON.parse(@response.body)
+    assert res.key?("error")
+
+    # Now try to retrieve the url WITH the passphrase
+    get "/r/#{url_token}.json?passphrase=asdf", headers: {"X-User-Email": @luca.email, "X-User-Token": @luca.authentication_token}
+    assert_response :success
+
+    res = JSON.parse(@response.body)
+    assert res.key?("payload")
+    assert_equal "https://the0x00.dev", res["payload"]
+  end
+
   def test_view_expiration
     post urls_path(format: :json), params: {url: {payload: "https://the0x00.dev", expire_after_views: 2}}, headers: {"X-User-Email": @luca.email, "X-User-Token": @luca.authentication_token}
     assert_response :success