Secure context

Also known as Elevation

You might have interacted with one already: ArcOS has a Secure Context, basically a glorified confirmation dialog that asks the user if they want to continue with any given operation. You can compare this to a sudo prompt in macOS or Linux, or the User Account Control dialog on Windows.

There are two ways to elevate: either you call UserDaemon.manuallyElevate (manual elevation), or you call AppProcess.elevate (predefined elevation). Here's both methods expained in detail:

Manual elevation

To manually elevate, call the UserDaemon.manuallyElevate method in your process class. Do it like this:

const image = await this.fs.direct(util.join(workingDirectory, "icon.png"));
const elevated = await this.userDaemon?.manuallyElevate({
   what: "ArcOS needs your permission to delete an application",
   image,
   title: "Minesweeper",
   description: "by Izaak Kuipers",
   level: 1, // 0-low, 1-medium, 2-high severity
});

Here I'm asking the user permission to delete the Minesweeper application, with a medium severity and an image URL I loaded using direct file access. The asynchronous function returns a boolean that returns true if the user permitted the elevation request.

The manuallyElevate method is asynchronous, it has to be awaited.

Predefined elevation

A predefined elevation is saved in the elevations property of your app's process. For example, if you have an elevation that needs to be presented a bunch of times, you can save it in this property and elevate using an ID later. Here's how:

In your render method:

async render() {
   // . . .
   this.elevations.deleteMinesweeper = {
    what: "ArcOS needs your permission to delete an application",
    image: await this.fs.direct(util.join(workingDirectory, "icon.png")),
    title: "Minesweeper",
    description: "by Izaak Kuipers",
    level: 1, // 0-low, 1-medium, 2-high severity
  }
  // . . .
}

And then anywhere else in your app process:

const elevated = await this.elevate("deleteMinesweeper");

The elevate method is asynchronous, it has to be awaited.

When should you elevate?

You should elevate only when you're about to perform big operations that the user might regret. Basically, if you're about to delete an app, change a security setting, kill a process, you're expected to elevate. You don't have to elevate for deleting a note from a ToDo list, just use the MessageBox function for that.