@suffolklitlab/alkiln 5.12.0-delete2 → 5.12.0-delete4

package/.github/workflows/github_server.yml

@@ -43,18 +43,22 @@ jobs:
     #### Developer note: You can probably leave out these specific
     #### environment variables. You may not even need the `env`
     #### keyword or values at all. See
-    #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing#env-vars
+    #### https://assemblyline.suffolklitlab.org/docs/alkiln/writing#env-vars
     env:
       SECRET_VAR1: secret-var1-value
       SECRET_VAR2: secret-var2-value
       SECRET_FOR_MISSING_FIELD: secret for missing field
+      INVALID_API_KEY: invalidAPIkey
+      EMPTY_STRING: ""
+      USER_NO_PERMISSIONS_EMAIL: alkiln@example.com
+      USER_NO_PERMISSIONS_PASSWORD: User123^
       
     steps:
       # Place the root directory in this branch to access
       # relative paths to action files
       - uses: actions/checkout@v4
 
-      - name: ALKiln - Start the isolated temporary docassemble server on GitHub
+      - name: "ALKiln - Start the isolated temporary docassemble server on GitHub"
         id: github_server
         #### Developer note: you'll need to replace `uses: ./action_for_github_server`
         #### with the path to ALKiln’s repository name and branch name. For example,
@@ -71,13 +75,50 @@ jobs:
         shell: bash
 
       #### Developer note: You can probably leave this out
-      # # Optional debugging to explore things like docker issues
-      # - name: Docker debug tmate session
-      #   if: ${{ failure() && github.event.inputs.enable_tmate == 'true' }}
-      #   uses: mxschmitt/action-tmate@v3
+      - name: "Create a new normal user with an API key env var"
+        env:
+          SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
+          KEY: ${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}
+        run: |
+          # Create user and their API key
+          sudo apt-get install jq
+
+          # https://docassemble.org/docs/api.html#user_new
+          user_data=$(curl -X POST \
+            ${{ env.SERVER_URL }}/api/user/new \
+            -H 'Content-Type: application/json' \
+            -d '{
+              "key": "${{ env.KEY }}",
+              "username": "${{ env.USER_NO_PERMISSIONS_EMAIL }}",
+              "password": "${{ env.USER_NO_PERMISSIONS_PASSWORD }}"
+            }')
+          echo "User data:"
+          echo "$user_data"
+
+          user_id=$(echo "$user_data" | jq '.user_id' -r)
+
+          # https://docassemble.org/docs/api.html#api_user_user_id_api_post
+          new_key=$(curl -X POST \
+            ${{ env.SERVER_URL }}/api/user/"$user_id"/api \
+            -H 'Content-Type: application/json' \
+            -d '{
+              "key": "${{ env.KEY }}",
+              "name": "alkiln_key",
+              "method": "none"
+            }')
+          echo "User new key:"
+          echo "$new_key"
+
+          echo "USER_NO_PERMISSIONS_API_KEY=$new_key" >> "$GITHUB_ENV"
+
+      ### Developer note: You can probably leave this out
+      # Optional debugging to explore things like docker issues
+      - name: Docker debug tmate session
+        #if: ${{ failure() && github.event.inputs.enable_tmate == 'true' }}
+        uses: mxschmitt/action-tmate@v3
 
       #### Developer note: You can probably leave this out
-      - name: Run ALKiln - Env vars for our own tests from server output
+      - name: "Create other env vars for our own tests from server output"
         run: |
           echo "USER1_EMAIL=${{ steps.github_server.outputs.DA_ADMIN_EMAIL }}" >> $GITHUB_ENV
           echo "USER1_PASSWORD=${{ steps.github_server.outputs.DA_ADMIN_PASSWORD }}" >> $GITHUB_ENV
@@ -106,12 +147,12 @@ jobs:
           ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || '(not @error) and (not @temp_error)' }}"
         with:
           #### Developer note: Required inputs. See
-          #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#sandbox-inputs
+          #### https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#sandbox-inputs
           SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           INSTALL_METHOD: "server"
           #### Developer note: You can probably leave the rest out
-          #### To learn more, see https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
+          #### To learn more, see https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           ALKILN_TAG_EXPRESSION: "${{ env.ALKILN_TAG_EXPRESSION }}"
           ALKILN_VERSION: delete
 

package/.github/workflows/log_code_tests.yml

@@ -24,4 +24,6 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install
+      - name: Docker debug tmate session
+        uses: mxschmitt/action-tmate@v3
       - run: npm run codes

package/.github/workflows/playground.yml

@@ -43,6 +43,11 @@ jobs:
       PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
       USER1_EMAIL: ${{ secrets.USER1_EMAIL }}
       USER1_PASSWORD: ${{ secrets.USER1_PASSWORD }}
+      USER_NO_PERMISSIONS_EMAIL: ${{ secrets.USER_NO_PERMISSIONS_EMAIL }}
+      USER_NO_PERMISSIONS_PASSWORD: ${{ secrets.USER_NO_PERMISSIONS_PASSWORD }}
+      USER_NO_PERMISSIONS_API_KEY: ${{ secrets.USER_NO_PERMISSIONS_API_KEY }}
+      INVALID_API_KEY: invalidAPIkey
+      EMPTY_STRING: ""
       SECRET_VAR1: secret-var1-value
       SECRET_VAR2: secret-var2-value
       SECRET_FOR_MISSING_FIELD: secret for missing field
@@ -64,10 +69,10 @@ jobs:
           ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || '(not @error) and (not @temp_error)' }}"
         with:
           #### Developer note: Required ALKiln inputs. You can read more at
-          #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#githubNyou-inputs
+          #### https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#githubNyou-inputs
           SERVER_URL: "${{ env.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ env.DOCASSEMBLE_DEVELOPER_API_KEY }}"
-          #### Developer note: See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
+          #### Developer note: See https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#optional-inputs
           #### You can probably leave this out
           # Internal: docassemble changes sometimes break @a11y tests. That is
           # a da problem, not ours. We will trigger these tests manually when we

package/CHANGELOG.md

@@ -51,11 +51,12 @@ Format:
 
 ### Fixed
 
-- Now delete interviews upon interview completion for signed in users
+- Now ALKiln deletes interviews upon interview completion for [signed in users](https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#sign-in) as long as the user has an API key. Also, the author must have used the ["start interview" Step](https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#start-interview) to get to the interview. Admins can give a regular user an API key with https://docassemble.org/docs/api.html#api_user_user_id_api_post. See [#831](https://github.com/SuffolkLITLab/ALKiln/issues/831).
 
 ### Internal
 
-- Test deleting interviews upon interview completion for signed in users
+- Test deleting interviews upon interview completion for signed in users.
+- Switch to mostly using a lowest-access-level user account for actually running interviews.
 - Added @temp_error to neutralize tests that are getting undesired errors right now, but which we anticipate being fixed soon. We want to ignore them for a short while. For example, an upstream change temporarily breaking some tests.
 
 ## [5.12.0] - 2024-06-06

package/lib/docassemble/docassemble_api_REST.js

@@ -31,6 +31,27 @@ da.get_dev_id = async function ( timeout ) {
 };  // Ends da.get_dev_id()
 
 
+da.get_api_key_info = async function ( timeout, { api_key = null, server_url = null }) {
+  /** Get information about an API key owned by the user of the given API key. */
+  let options = {
+    method: 'GET',
+    headers: {'X-API-Key': api_key},
+    url: `${ server_url }/api/user/api`,
+    params: {
+      api_key: api_key,
+    },
+    timeout: timeout,
+  };
+
+  try {
+    return await axios.request( options );
+  } catch (error) {
+    let response = error.response || { data: null }
+    throw {...error.toJSON(), data: response.data};
+  }
+};  // Ends da.get_api_key_info()
+
+
 // node -e 'require("./lib/docassemble/docassemble_api_REST.js").delete_project()'
 da.delete_project = async function ( timeout ) {
   /* Delete a project on the user's da server. */

package/lib/docassemble/docassemble_api_interface.js

@@ -177,6 +177,67 @@ da_i.get_dev_id = async function ( dev_id_options ) {
   return dev_id;
 };  // Ends da_i.get_dev_id();
 
+da_i.get_api_key_access_status = async function ({ timeout = null, api_key = null }) {
+  /** Check if the API key has minimal authorization on the server.
+  *    See https://docassemble.org/docs/api.html#api_user_api_get.
+  *
+  * @param options {obj} Options for getting authorization of the API key
+  * @param options.api_key {str | null} Required. The API key to test.
+  * @param options.timeout {int | null} Optional. Max MS
+  *    to allow for server request.
+  */
+
+  let auth_data = {
+    codes: [ 1 ],
+    has_auth: null,
+    messages: [`API key authorization is not yet determined.`],
+    error: null
+  }
+
+  // Skip this for tests run from ALKilnInThePlayground
+  if ( session_vars.get_origin() === 'playground' ) {
+    auth_data.codes.push( 2 );
+    auth_data.messages.push( `API keys are unnecessary for tests run in the Playground.` );
+  }
+
+  if ( typeof api_key !== `string` ) {
+    auth_data.codes.push( 3 );
+    auth_data.messages.push( `The given API key is not a string. Type: ${ typeof api_key }`);
+  }
+
+  if ( auth_data.codes.length === 1 ) {
+    // Default timeouts
+    timeout = timeout || DEFAULT_MAX_REQUEST_MS;
+    try {
+      let response = await _da_REST.get_api_key_info( timeout, {
+        api_key,
+        server_url: session_vars.get_da_server_url(),
+      });
+      auth_data.has_auth = true;
+      auth_data.codes = [ 6 ];
+      auth_data.messages = [ `This API key has at least basic authorization on this server.` ];
+
+    } catch ( error ) {
+      auth_data.error = error;
+      if ( error.status === 403 ) {
+        auth_data.has_auth = false;
+        auth_data.codes = [ 4 ];
+        auth_data.messages = [ `This API is unverified on this server. It is probably missing or has been deleted.` ];
+      } else {
+        // Note on 404, non-existent key: 404 == 403 - Since we're using the
+        // key itself to get its own info, if it doesn't exist, we'll get 403
+        auth_data.codes = [ 5 ];
+        auth_data.messages = [ `This API key threw a non-403 error.` ];
+      }  // ends error status
+    }  // ends try
+  }  // ends auth_data.codes only has the first code
+
+  log.info({ type: `da api info`, code: `ALK0202`,
+    pre: `API key authentication info`, data: auth_data });
+
+  return auth_data;
+};  // Ends da_i.get_api_key_access_status()
+
 // node -e 'require("./lib/docassemble/docassemble_api_interface.js").delete_project( "create1" )'
 da_i.delete_project = async function ( delete_options ) {
   /** Delete a project on the user's da server. Do we need to watch
@@ -231,7 +292,7 @@ da_i.quietly_delete_one_interview = async function ( timeout, { interview = {},
   /** Try to delete an interview using all available API keys. Fail silently.
    *    Example failure: the test did not log in any users and the testing
    *    account's role prevents access to other user's interviews. */
-  api_keys = normalize_api_keys( api_keys );
+
   let responses = [];
   for ( let api_key of api_keys ) {
     try {
@@ -263,8 +324,6 @@ da_i.get_interviews = async function ({ interviews = {}, api_keys = [], options
   /** Return an object of interviews that exist on the server
    *    that match the given interviews. Keys are the session ids. */
 
-  api_keys = normalize_api_keys( api_keys );
-
   let fetched_interviews = {};
   if ( interviews ) {
     for ( let id in interviews ) {
@@ -285,7 +344,6 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
 
   // Defaults
   let { timeout } = options || { timeout: DEFAULT_MAX_REQUEST_MS };
-  api_keys = normalize_api_keys( api_keys );
 
   if ( interview && interview.uid ) {
     for ( let api_key of api_keys ) {
@@ -304,6 +362,7 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
         } else {
           log.debug({ type: `da api info`, code: `ALK0194`, pre: `Status ${ response.status }. Cannot find ${ interview.uid }`});
         }
+
       } catch ( error ) {
         error.interview = interview;
         let msg = `${ error.status || `No error.status.` } ${ error.statusText || error.data || `No error.statusText.` } Ran into an error when getting the interview ${ interview.uid }. See https://docassemble.org/docs/api.html#interviews.`
@@ -317,11 +376,3 @@ da_i.get_interview = async function ({ interview = {}, api_keys = [], options =
   return null;
 
 };  // Ends da_i.get_interview()
-
-let normalize_api_keys = function ( api_keys = [] ) {
-  /** Ensure the dev API key is in the api_keys list. */
-  let dev_key = session_vars.get_dev_api_key();
-  if ( !api_keys ) { api_keys = [ dev_key ]; }
-  if ( !api_keys.includes( dev_key ) ) { api_keys.unshift( dev_key ); }
-  return api_keys;
-};

package/lib/scope.js

@@ -16,7 +16,7 @@ const time = require('./utils/time');
 const log = require('./utils/log');
 const { waitForTimeout } = require('./utils/time');
 const files = require('./utils/files' );
-const server = require('./docassemble/docassemble_api_interface');
+const da_api = require('./docassemble/docassemble_api_interface');
 const wrapPromiseWithTimeout = require('./cucumber_8_shim');
 const reports = require(`./utils/reports`);
 
@@ -339,7 +339,7 @@ module.exports = {
       // This code assumes a reasonable response time would be n seconds if the
       // server is up and that a server reload/restart won't take less than n seconds.
       // Also, it's non-blocking, so it doesn't slow down tests
-      let is_up = await server.is_server_responding({ timeout: scope.server_check_interval_ms });
+      let is_up = await da_api.is_server_responding({ timeout: scope.server_check_interval_ms });
       // Add status to the beginning of the list to make truncating easier
       scope.server_statuses.unshift( is_up );
 
@@ -2996,10 +2996,20 @@ module.exports = {
       // Save API key to clean up interviews later. Nice to have, not critical
       if ( api_key_secret_name ) {
         let api_key = process.env[ api_key_secret_name ];
-        let api_key_msg = `The api_key GitHub SECRET "${ api_key_secret_name }" doesn't exist. Check for a typo and check your workflow file.`
+        let api_key_msg = `The API key in the variable "${ api_key_secret_name }" is missing. Check for a typo in your test, workflow file, GitHub secret, or server config.`
         if ( api_key === undefined ) {
           reports.addToReport( scope, { type: `warning`, code: `ALK0199`, value: api_key_msg });
+        } else if ( api_key === `` ) {
+          reports.addToReport( scope, { type: `warning`, code: `ALK0200`,
+            value: `ALKiln found the API key in the variable "${ api_key_secret_name }", but it was empty. It had no text in it. Edit the value of the GitHub secret or server config variable called "${ api_key_secret_name }".` });
         } else {
+          let access_info = await da_api.get_api_key_access_status({ api_key });
+          if ( !access_info.has_auth ) {
+          reports.addToReport( scope, { type: `warning`, code: `ALK0201`,
+            value: `The server rejected the API key in the variable "${ api_key_secret_name }". Does it exist on this server? Was it deleted somehow? You can always make a new one.` });
+          }
+          // Even if it doesn't have access, give it a shot anyway.
+          // Maybe we got something wrong.
           scope.scenarios.get( scope.scenario_id ).api_keys.push( api_key );
         }
       }

package/lib/steps.js

@@ -140,7 +140,7 @@ Before(async (scenario) => {
   scope.scenario_id = uuidv4();
   scope.scenarios.set( scope.scenario_id, {} );
   scope.scenarios.get( scope.scenario_id ).interviews = {};
-  scope.scenarios.get( scope.scenario_id ).api_keys = [ session_vars.get_dev_api_key() ];
+  scope.scenarios.get( scope.scenario_id ).api_keys = [];
   scope.expected_status = null;
   scope.expected_in_report = null;
   scope.expected_not_in_report = null;
@@ -286,14 +286,14 @@ Given(
   { timeout: -1 },
   async ( email, password, api_key ) => {
   /** Uses the names of environment variables (most often GitHub SECRETs) to
-  *     log into an account on the user's server. Must be SECRETs to stay secure.
+  *     log into an account on the user's server. Must be secure.
   * 
   * Variations:
-  * I sign into the server with the email "USER1_EMAIL" and the password "USER1_PASSWORD" SECRETs
-  * I sign on with the email "USER1_EMAIL" and the password "USER1_PASSWORD" SECRETs
-  * I log in with "USER1_EMAIL" and "USER1_PASSWORD"
-  * I sign in with the email "USER1_EMAIL", the password "USER1_PASSWORD", and the API key "USER1_API_KEY"
-  * I sign in with "USER1_EMAIL", "USER1_PASSWORD", "USER1_API_KEY"
+  * I sign into the server with the email "USER2_EMAIL" and the password "USER2_PASSWORD"
+  * I sign on with the email "USER2_EMAIL" and the password "USER2_PASSWORD"
+  * I log in with "USER2_EMAIL" and "USER2_PASSWORD"
+  * I sign in with the email "USER2_EMAIL", the password "USER2_PASSWORD", and the API key "USER2_API_KEY"
+  * I sign in with "USER2_EMAIL", "USER2_PASSWORD", "USER2_API_KEY"
   */
   // `page` timeout will deal with custom timeout
   // Couldn't test the timeout for tapping the button because there's not
@@ -1205,11 +1205,11 @@ Then(/of two interviews, I delete one __internal__/i, async () => {
 
   // Check that both interviews exist on the server. 1 √ 2 √
   let api_keys = scope.scenarios.get( scope.scenario_id ).api_keys;
-  let existing_interviews = await da_api.get_interviews({ interviews, api_keys });
-  let existing_keys = Object.keys( existing_interviews );
+  let visible_interviews = await da_api.get_interviews({ interviews, api_keys });
+  let visible_keys = Object.keys( visible_interviews );
   expect(
-    existing_keys.length,
-    `2 interviews should be on the server. Instead: "${ existing_keys.join(', ') }"`
+    visible_keys.length,
+    `2 interviews should be on the server. Instead: "${ visible_keys.join(', ') }"`
   ).to.equal( 2 );
 
   // Delete one. 1 x 2 √
@@ -1233,24 +1233,23 @@ Then(/of two interviews, I delete one __internal__/i, async () => {
   // In After(), the other session should get deleted
 });
 
-Then(/as an anonymous user, I fail to delete an interview and get no error __internal__/i, async () => {
-  /** Test that an interview passes even when unable to delete an interview.
-   *    An API test
-   */
+Then(/I fail to delete (\d) detected interview(?:s)? and get no error __internal__/i, async ( num ) => {
+  /** Test that there is no error when ALKiln is unable to delete an interview. */
+  num = parseInt( num );
   // Make sure we started an interview
   let interviews = scope.scenarios.get( scope.scenario_id ).interviews;
   expect(
     Object.keys( interviews ).length,
-    `The test should have saved one interview session`
-  ).to.equal( 1 );
+    `The test should have saved ${ num } interview session(s)`
+  ).to.equal( num );
 
   // There should be no error about an unauthorized user
   let api_keys = scope.scenarios.get( scope.scenario_id ).api_keys;
-  let existing_interviews = await da_api.get_interviews({ interviews, api_keys });
-  let existing_keys = Object.keys( existing_interviews );
+  let visible_interviews = await da_api.get_interviews({ interviews, api_keys });
+  let visible_keys = Object.keys( visible_interviews );
   expect(
-    existing_keys.length,
-    `Anonymous user should detect 0 interviews on the server. Instead: "${ existing_keys.join(', ') }"`
+    visible_keys.length,
+    `User should detect 0 interviews on the server. Instead: "${ visible_keys.join(', ') }"`
   ).to.equal( 0 );
 
   // Deleting with an anonymous user should fail silently
@@ -1475,14 +1474,15 @@ After(async function(scenario) {
       let interviews = scope.scenarios.get( scope.scenario_id ).interviews;
       let api_keys = scope.scenarios.get( scope.scenario_id ).api_keys;
       await da_api.quietly_try_to_delete_interviews({ interviews, api_keys });
-      let existing_interviews = await da_api.get_interviews({ interviews, api_keys });
-      let existing_keys = Object.keys( existing_interviews );
+      let visible_interviews = await da_api.get_interviews({ interviews, api_keys });
+      let visible_keys = Object.keys( visible_interviews );
       // Deleting interviews is nice, but not non-critical. Don't bother the
       // user with it. Don't want to cover up a more meaningful failure (like
       // going to the wrong file). If it becomes a problem we can track it down later.
-      if ( existing_keys.length > 0 ) {
+      if ( visible_keys.length > 0 ) {
+        // Can an API key ever see an interview that it can't delete?
         log.debug({ type: `internal warning`, code: `ALK0197`,
-          pre: `${ existing_keys.length } interviews were not deleted: ${ existing_keys.join( ', ' ) }`
+          pre: `The API key can see ${ visible_keys.length } interviews that were not deleted: ${ visible_keys.join( ', ' ) }`
         });
       }
     } catch ( error ) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suffolklitlab/alkiln",
-  "version": "5.12.0-delete2",
+  "version": "5.12.0-delete4",
   "description": "Integrated automated end-to-end testing with docassemble, puppeteer, and cucumber.",
   "main": "lib/index.js",
   "scripts": {

package/tests/log_codes/check_codes.sh

@@ -16,7 +16,7 @@ fi
 # The grepped files will include the list of all the codes that have been
 # removed and are no longer used. Syntax used works with GitHub cli ([[:digit:]])
 # https://stackoverflow.com/a/6901221
-lines=$(grep -roh --exclude="tests/log_codes/check_codes.sh" --exclude="debug_log.txt" --exclude="cucumber-report.txt" --exclude-dir="node_modules" --exclude-dir='alkiln-*' --exclude-dir='_alkiln*' 'ALK[[:digit:]][[:digit:]][[:digit:]][[:digit:]]' "$directory")
+lines=$(grep -roh --exclude="tests/log_codes/check_codes.sh" --exclude="debug_log.txt" --exclude="cucumber-report.txt" --exclude-dir="./docassemble" --exclude-dir="node_modules" --exclude-dir='alkiln-*' --exclude-dir='_alkiln*' 'ALK[[:digit:]][[:digit:]][[:digit:]][[:digit:]]' "$directory")
 sorted=$(echo "$lines" | sort -n)