File and directory access entitlements

[bradgessler]

Entitlements is a security mechanism on the Terminalwire client that controls what resources a Terminalwire server can manipulate on the client. More at https://terminalwire.com/docs/client/security#entitlements.

By default, a Terminalwire CLI is only entitled to:

1. Read/write files from its $TERMINALWIRE_HOME/domains/example.com/storage/*.* directory, which enable the client to write files, like "cookies", to the host workstation.
2. Access standard IO streams including stdout, stderr, and stdin.

Here's a base entitlement policy: https://github.com/terminalwire/ruby/blob/main/gem/terminalwire-client/lib/terminalwire/client/entitlement/policy.rb

The exception to this hard coded CLI is the terminalwire client itself, which grants access in a hard coded policy to various directories within $TERMINALWIRE_HOME so that it can install, uninstall, and manage Terminalwire on each workstation.

https://github.com/terminalwire/ruby/blob/main/gem/terminalwire-client/lib/terminalwire/client/entitlement/policy.rb#L52-L96

The problem

Hard coded requirements would require client release each time a change is made to an entitlement. A more flexible approach is needed that lets the client specify entitlements that's written to a configuration store on the users workstation.

Potential solutions

Here's a few potential solutions to the problem, written here for community feedback. Note that more than one option may be considered or relevant.

Non-interactive terminalwire grant command-line

A non-interactive Terminalwire CLI could be built that users run ahead of time or after a command that requires an entitlement fails. That would look like this:

# Grant access to a folder in perpetuity
$ terminalwire grant path ~/my-themes/*.* --to example.com

Removing an entitlement might look like:

# Grant access to a folder in perpetuity
$ terminalwire revoke path ~/my-themes/*.* --to example.com

Interactive entitlement grants

A better developer experience might have interactive grants. That could work like this:

1. Server requests access to ~/my-themes, which has not yet been granted by user
2. Client receives request to access ~/my-themes, but detects there's no entitlement access, so it sends an error back to the client that the request has been denied
3. The server sends an entitlement request for the path to the client
4. The client prompts the user with an interactive entitlement request:

   The example.com app is requesting read & write access to the ~/my-themes directory:
    [x] Deny
    [ ] Approve once
    [ ] Approve for 30 days
   

5. If the user grants access, the server receives the response and tries the file operation again. If it doesn't, the client may display an error message.

Additional considerations

The examples above would provide basic access to files & directories, but additional concerns may need to be considered

Term of grants

What's a sensible default for the term of a grant? Should they time-out after 30 days? 365 days? Never?

Configuration file format

Entitlements could be stored in a file at $TERMINALWIRE_HOME/domains/example.com/entitlement.json. This would make it possible for end-users to inspect these files to audit their security exposure. It might also make it possible for client to distribute entitlement files for various configurations.

Entitlements during the installation phase

How important is it to grant entitlements when a Terminalwire application is installed? In theory a Terminalwire application could do this when it's first run, which is probably better.