fleet/website/api/controllers/android-proxy/issue-command-on-android-device.js

module.exports = {


  friendlyName: 'Issue command on android device',


  description: 'Issues an AMAPI command (e.g. LOCK, RESET_PASSWORD, WIPE) to a device of an Android enterprise.',


  inputs: {
    androidEnterpriseId: {
      type: 'string',
      required: true,
    },
    deviceId: {
      type: 'string',
      required: true,
    },
    // Captured from the `:deviceId::issueCommand` route. Validated here so requests targeting any
    // other colon-suffixed action (e.g. `/devices/<id>:somethingElse`) are rejected up front rather
    // than silently invoking issueCommand. Mirrors how `modify-enterprise-app-policy.js` captures
    // `googleAction`.
    issueCommand: {
      type: 'string',
      required: true,
      isIn: ['issueCommand'],
    },
    // AMAPI Command fields. Inputs are declared explicitly (rather than forwarding req.body) so the
    // proxy's accepted surface is visible. `type` is not constrained via isIn so the Fleet server can
    // issue any AMAPI command type without a proxy change. Adding entirely new Command FIELDS (e.g. a
    // future *Params sibling Google adds to AMAPI) does still require updating this list.
    type: {
      type: 'string',
      required: true,
      description: 'The AMAPI command type (e.g. LOCK, RESET_PASSWORD, REBOOT, RELINQUISH_OWNERSHIP, CLEAR_APP_DATA, START_LOST_MODE, STOP_LOST_MODE, ADD_ESIM, REMOVE_ESIM, REQUEST_DEVICE_INFO, WIPE).',
    },
    duration: {
      type: 'string',
      description: 'How long the command remains valid (e.g. "315360000s"). Forwarded to AMAPI verbatim.',
    },
    newPassword: {
      type: 'string',
      description: 'New device password for RESET_PASSWORD. Fleet sends an empty string to clear the passcode, so an explicitly empty value is preserved.',
    },
    resetPasswordFlags: {
      type: ['string'],
      description: 'AMAPI reset-password flags (REQUIRE_ENTRY, DO_NOT_ASK_CREDENTIALS_ON_BOOT, LOCK_NOW).',
    },
    wipeParams: {
      type: 'ref',
      description: 'AMAPI WipeParams object (may be empty {}). Required by AMAPI for WIPE commands.',
    },
    addEsimParams: {
      type: 'ref',
      description: 'AMAPI AddEsimParams object, for ADD_ESIM commands.',
    },
    removeEsimParams: {
      type: 'ref',
      description: 'AMAPI RemoveEsimParams object, for REMOVE_ESIM commands.',
    },
    clearAppsDataParams: {
      type: 'ref',
      description: 'AMAPI ClearAppsDataParams object, for CLEAR_APP_DATA commands.',
    },
    startLostModeParams: {
      type: 'ref',
      description: 'AMAPI StartLostModeParams object, for START_LOST_MODE commands.',
    },
    stopLostModeParams: {
      type: 'ref',
      description: 'AMAPI StopLostModeParams object, for STOP_LOST_MODE commands.',
    },
    requestDeviceInfoParams: {
      type: 'ref',
      description: 'AMAPI RequestDeviceInfoParams object, for REQUEST_DEVICE_INFO commands.',
    },
  },


  exits: {
    success: { description: 'The command was successfully issued to the Android device. The AMAPI Operation is returned.' },
    missingAuthHeader: { description: 'This request was missing an authorization header.', responseType: 'unauthorized'},
    unauthorized: { description: 'Invalid authentication token.', responseType: 'unauthorized'},
    notFound: { description: 'No Android enterprise found for this Fleet server.', responseType: 'notFound' },
    enterpriseNotAccessible: { description: 'Fleet is not authorized to manage this Android enterprise.', responseType: 'notFound' },
    deviceNoLongerManaged: { description: 'The specified device is no longer managed by the Android enterprise.', responseType: 'notFound' },
    deviceNotFound: {description: 'The specified device does not exist in this Android enterprise', responseType: 'notFound'},
    managementApiError: { statusCode: 503, description: 'The Android management API returned a transient 5xx error.' },
  },


  fn: async function ({
    androidEnterpriseId, deviceId, type, duration, newPassword, resetPasswordFlags,
    wipeParams, addEsimParams, removeEsimParams, clearAppsDataParams,
    startLostModeParams, stopLostModeParams, requestDeviceInfoParams,
  }) {

    // Extract fleetServerSecret from the Authorization header
    let authHeader = this.req.get('authorization');
    let fleetServerSecret;

    if (authHeader && authHeader.startsWith('Bearer')) {
      fleetServerSecret = authHeader.replace('Bearer', '').trim();
    } else {
      throw 'missingAuthHeader';
    }

    // Authenticate this request
    let thisAndroidEnterprise = await AndroidEnterprise.findOne({
      androidEnterpriseId: androidEnterpriseId
    });

    // Return a 404 response if no records are found.
    if (!thisAndroidEnterprise) {
      throw 'notFound';
    }
    // Return an unauthorized response if the provided secret does not match.
    if (thisAndroidEnterprise.fleetServerSecret !== fleetServerSecret) {
      throw 'unauthorized';
    }

    // Build the AMAPI Command body from declared inputs (not req.body) so the proxy's accepted surface
    // stays explicit. Use `!== undefined` rather than truthy checks because Fleet relies on forwarding
    // an empty newPassword ("") to clear the device passcode and an empty wipeParams ({}) for WIPE.
    let commandBody = { type: type };
    if (duration !== undefined) {
      commandBody.duration = duration;
    }
    if (newPassword !== undefined) {
      commandBody.newPassword = newPassword;
    }
    if (resetPasswordFlags !== undefined) {
      commandBody.resetPasswordFlags = resetPasswordFlags;
    }
    if (wipeParams !== undefined) {
      commandBody.wipeParams = wipeParams;
    }
    if (addEsimParams !== undefined) {
      commandBody.addEsimParams = addEsimParams;
    }
    if (removeEsimParams !== undefined) {
      commandBody.removeEsimParams = removeEsimParams;
    }
    if (clearAppsDataParams !== undefined) {
      commandBody.clearAppsDataParams = clearAppsDataParams;
    }
    if (startLostModeParams !== undefined) {
      commandBody.startLostModeParams = startLostModeParams;
    }
    if (stopLostModeParams !== undefined) {
      commandBody.stopLostModeParams = stopLostModeParams;
    }
    if (requestDeviceInfoParams !== undefined) {
      commandBody.requestDeviceInfoParams = requestDeviceInfoParams;
    }

    // Get the shared Google API auth client with the getAndroidManagementAuthorizationClient helper.
    // Note: we are doing this outside of the sails.helpers.flow.build() so any errors related to the website's credentials returned by the helper are not intercepted.
    let androidManagementAuthClient = await sails.helpers.androidProxy.getAndroidManagementAuthorizationClient();

    // Issue the command to the device for this Android enterprise.
    // Note: We're using sails.helpers.flow.build here to handle any errors that occur using google's node library.
    let issueCommandResponse = await sails.helpers.flow.build(async () => {
      let { google } = require('googleapis');
      let androidManagementConnection = google.androidmanagement({version: 'v1', auth: androidManagementAuthClient});
      // [?]: https://googleapis.dev/nodejs/googleapis/latest/androidmanagement/classes/Resource$Enterprises$Devices.html#issueCommand
      sails.androidProxyApiRequestCount++;// Count this Android Management API request toward the per-minute total logged in api/hooks/custom/index.js.
      let response = await androidManagementConnection.enterprises.devices.issueCommand({
        name: `enterprises/${androidEnterpriseId}/devices/${deviceId}`,
        requestBody: commandBody,
      });
      return response.data;
    }).intercept({status: 429}, (err)=>{
      // If the Android management API returns a 429 response, log an additional warning that will trigger a help-p1 alert.
      sails.log.warn(`p1: Android management API rate limit exceeded!`);
      return new Error(`When attempting to issue a command to a device for an Android enterprise (${androidEnterpriseId}), an error occurred. Error: ${err}`);
    }).intercept({status: 403}, ()=>{
      // If the Android management API returns a 403 response, return a enterpriseNotAccessible (notFound) response to the Fleet server.
      return {'enterpriseNotAccessible': 'Fleet is not authorized to manage this Android enterprise.'};
    }).intercept({status: 404}, ()=>{
      // If the Android management API returns a 404 response, return a deviceNotFound (notFound) response to the Fleet server.
      return 'deviceNotFound';
    }).intercept((err)=>{
      let errorString = err.toString();
      if (errorString.includes('Device is no longer being managed')) {
        return {'deviceNoLongerManaged': 'The device is no longer managed by the Android enterprise.'};
      }
      if([502, 503, 504].includes(err.status)) {
        return {'managementApiError': `The Android management API returned a transient 5xx error: ${err}`};
      }
      return new Error(`When attempting to issue a command to a device for an Android enterprise (${androidEnterpriseId}), an error occurred. Error: ${require('util').inspect(err)}`);
    });


    // Return the AMAPI Operation back to the Fleet server.
    return issueCommandResponse;

  }


};