Redesign interface #11

yarmo commented 2022年03月26日 18:11:25 +01:00

The CLI needs to be thought through and fundamentally redesigned.

Currently:

# Generate Keyoxide profiles and verify their identity claims
keyoxide verify hkp:3637202523e7c1309ab79e99ef2dc5827b445f4b
keyoxide verify hkp:test@doip.rocks

Using guidelines from https://clig.dev, here's one proposal:

# Show basic information about a key (in automatic mode)
keyoxide 3637202523e7c1309ab79e99ef2dc5827b445f4b
keyoxide test@doip.rocks
# Force HKP
keyoxide --hkp test@doip.rocks
# Force HKP and specify server
keyoxide --hkp --hkp-server keys.openpgp.org test@doip.rocks
# Generate a profile and verify their identity claims (--profile or -p)
keyoxide -p 3637202523e7c1309ab79e99ef2dc5827b445f4b
# Generate a more detailed profile (--details or -d)
keyoxide -pd 3637202523e7c1309ab79e99ef2dc5827b445f4b
# Generate a profile based on a signature profile or local key
keyoxide -p ./profile.asc
# Verify a signed document against a key (--verify or -v)
keyoxide -v ./signed-doc.asc 3637202523e7c1309ab79e99ef2dc5827b445f4b
# Encrypt a message (--encrypt or -e)
keyoxide -e "Secret stuff, yo" 3637202523e7c1309ab79e99ef2dc5827b445f4b
keyoxide --encrypt-file ./message.txt 3637202523e7c1309ab79e99ef2dc5827b445f4b

The CLI needs to be thought through and fundamentally redesigned. Currently: ```bash # Generate Keyoxide profiles and verify their identity claims keyoxide verify hkp:3637202523e7c1309ab79e99ef2dc5827b445f4b keyoxide verify hkp:test@doip.rocks ``` Using guidelines from https://clig.dev, here's one proposal: ```bash # Show basic information about a key (in automatic mode) keyoxide 3637202523e7c1309ab79e99ef2dc5827b445f4b keyoxide test@doip.rocks # Force HKP keyoxide --hkp test@doip.rocks # Force HKP and specify server keyoxide --hkp --hkp-server keys.openpgp.org test@doip.rocks # Generate a profile and verify their identity claims (--profile or -p) keyoxide -p 3637202523e7c1309ab79e99ef2dc5827b445f4b # Generate a more detailed profile (--details or -d) keyoxide -pd 3637202523e7c1309ab79e99ef2dc5827b445f4b # Generate a profile based on a signature profile or local key keyoxide -p ./profile.asc # Verify a signed document against a key (--verify or -v) keyoxide -v ./signed-doc.asc 3637202523e7c1309ab79e99ef2dc5827b445f4b # Encrypt a message (--encrypt or -e) keyoxide -e "Secret stuff, yo" 3637202523e7c1309ab79e99ef2dc5827b445f4b keyoxide --encrypt-file ./message.txt 3637202523e7c1309ab79e99ef2dc5827b445f4b ```

caesar commented 2022年03月27日 01:48:40 +01:00

Personally, I prefer the verb-based approach used by tools like git, homebrew, npm, and others – in fact, what keyoxide-cli already has, except that the only verb currently supported is verify.
I find this verb-based interface much more intuitive, and easier to learn and remember without reference to a man page. In particular, it's clear that each actions is exclusive (with your flag-based version, for example, what happens if I use the -v and -p or -e flags together?)

I must say I find the terminology of 'generating a profile' rather confusing. Currently keyoxide-web uses that terminology simply to refer to verifying claims and displaying the results, whereas I would have expected 'generating a profile' to perhaps actually create the claims and add them to my key.
With that said, I'm assuming when you used that term above (for your -p flag) you meant it to be the same as the current verify verb. But how does that differ from your first example, "Show basic information about a key"? Does that not perform any verification of claims?

One problem that needs some consideration is that once we introduce signature verification, verify is potentially ambiguous about whether it's verifying identity claims or signatures.
A possible solution would be for verifying identity claimns to simply be the default, and use verify to verify signatures, since that terminology is already widely used in the PGP ecosystem.

The only reason for verifying identity claims not to be the default, that I can see, is if you envisage keyoxide becoming a general purpose keyring or cryptography tool, so that verifying claims was no longer its primary purpose.

The verb-based interface I envisage would be something like the following:

# Verify claims and display results (auto mode)
$ keyoxide test@doip.rocks
$ keyoxide 3637202523e7c1309ab79e99ef2dc5827b445f4b
$ keyoxide ./key.asc
# Force a particular protocol (--wkd or --hkp)
$ keyoxide --wkd test@doip.rocks
$ keyoxide --hkp test@doip.rocks
# Specify a keyserver (--hkp-server implies --hkp)
$ keyoxide --hkp-server keys.openpgp.org test@doip.rocks
# Show basic information about a key (I'm not sure this is useful)
$ keyoxide info test@doip.rocks
# Show more details of verification results
$ keyoxide --detail test@doip.rocks
# or maybe
$ keyoxide --verbose test@doip.rocks
# but maybe --verbose should just be for extra logging
# Encrypt a message
$ keyoxide encrypt test@doip.rocks ./message.txt 
$ echo "Secret stuff, yo" > keyoxide encrypt test@doip.rocks
# Having the input after the recipient ID helps to make it optional,
# so it can come from stdin. It could also prompt for a message if nothing
# is provided and stdin is empty, or even open $EDITOR like `git commit`
# Verify a signed document
$ keyoxide verify ./doc.sig
# Verify a detatched signature
$ keyoxide verify ./doc.sig ./doc
# It shouldn't be necessary to specify the key; that's embedded in the
# signature (Keyoxide must obviously display it).
# But if wanted, a flag could be added like this:
$ keyoxide verify --key test@doip.rocks ./doc.sig

I'm half asleep, so I'll look at this again tomorrow,as well as responding on the other issues 😉

Personally, I prefer the verb-based approach used by tools like git, homebrew, npm, and others – in fact, what keyoxide-cli already has, except that the only verb currently supported is `verify`. I find this verb-based interface much more intuitive, and easier to learn and remember without reference to a man page. In particular, it's clear that each actions is exclusive (with your flag-based version, for example, what happens if I use the `-v` and `-p` or `-e` flags together?) I must say I find the terminology of 'generating a profile' rather confusing. Currently keyoxide-web uses that terminology simply to refer to verifying claims and displaying the results, whereas I would have expected 'generating a profile' to perhaps actually create the claims and add them to my key. With that said, I'm assuming when you used that term above (for your `-p` flag) you meant it to be the same as the current `verify` verb. But how does that differ from your first example, "Show basic information about a key"? Does that not perform any verification of claims? One problem that needs some consideration is that once we introduce signature verification, `verify` is potentially ambiguous about whether it's verifying *identity claims* or *signatures*. A possible solution would be for verifying identity claimns to simply be the default, and use `verify` to verify signatures, since that terminology is already widely used in the PGP ecosystem. The only reason for verifying identity claims not to be the default, that I can see, is if you envisage keyoxide becoming a general purpose keyring or cryptography tool, so that verifying claims was no longer its *primary* purpose. The verb-based interface I envisage would be something like the following: ```shell # Verify claims and display results (auto mode) $ keyoxide test@doip.rocks $ keyoxide 3637202523e7c1309ab79e99ef2dc5827b445f4b $ keyoxide ./key.asc # Force a particular protocol (--wkd or --hkp) $ keyoxide --wkd test@doip.rocks $ keyoxide --hkp test@doip.rocks # Specify a keyserver (--hkp-server implies --hkp) $ keyoxide --hkp-server keys.openpgp.org test@doip.rocks # Show basic information about a key (I'm not sure this is useful) $ keyoxide info test@doip.rocks # Show more details of verification results $ keyoxide --detail test@doip.rocks # or maybe $ keyoxide --verbose test@doip.rocks # but maybe --verbose should just be for extra logging # Encrypt a message $ keyoxide encrypt test@doip.rocks ./message.txt $ echo "Secret stuff, yo" > keyoxide encrypt test@doip.rocks # Having the input after the recipient ID helps to make it optional, # so it can come from stdin. It could also prompt for a message if nothing # is provided and stdin is empty, or even open $EDITOR like `git commit` # Verify a signed document $ keyoxide verify ./doc.sig # Verify a detatched signature $ keyoxide verify ./doc.sig ./doc # It shouldn't be necessary to specify the key; that's embedded in the # signature (Keyoxide must obviously display it). # But if wanted, a flag could be added like this: $ keyoxide verify --key test@doip.rocks ./doc.sig ``` I'm half asleep, so I'll look at this again tomorrow,as well as responding on the other issues 😉

yarmo commented 2022年03月27日 09:30:49 +02:00

I find this verb-based interface much more intuitive, and easier to learn and remember

Agreed. In general, I would prefer verb-based.

what happens if I use the -v and -p or -e flags together?

Euuhhhhhh

I must say I find the terminology of 'generating a profile' rather confusing.

In the beginning (a little over a year ago), it made a lot of sense. I too am wondering if we could improve that terminology as well, compile a clear vocabulary so that across clients, across implementations, words have clear meaning.

With that said, I'm assuming when you used that term above (for your -p flag) you meant it to be the same as the current verify verb. But how does that differ from your first example, "Show basic information about a key"? Does that not perform any verification of claims?

Indeed, -p would have been the same as the current verify. I want to provide an option to just get info about a key, maybe even see the claims but not verify them (which consumes internet). After getting some sleep, I realize this should not be the default, so I propose a --no-verify-claims flag for this scenario.

verify is potentially ambiguous about whether it's verifying identity claims or signatures

Yup, very much so. This is the reason I considered flag-based, but I think you're solution is quite elegant: no verb for profiles and claim verification, verify for signature verification, encrypt for encryption.

The only reason for verifying identity claims not to be the default, that I can see, is if you envisage keyoxide becoming a general purpose keyring or cryptography tool, so that verifying claims was no longer its primary purpose.

I don't :) identity verification should be central and first, with sig verification and message encryption being secondary. No other functions are really planned.

Creating profiles I think should be handled by a different utility (keyoxide-gen) or use a new verb here (keyoxide generate or keyoxide create). And yes, here's our confusion about generation back again...

> I find this verb-based interface much more intuitive, and easier to learn and remember Agreed. In general, I would prefer verb-based. > what happens if I use the -v and -p or -e flags together? Euuhhhhhh > I must say I find the terminology of 'generating a profile' rather confusing. In the beginning (a little over a year ago), it made a lot of sense. I too am wondering if we could improve that terminology as well, compile a clear vocabulary so that across clients, across implementations, words have clear meaning. > With that said, I'm assuming when you used that term above (for your -p flag) you meant it to be the same as the current verify verb. But how does that differ from your first example, "Show basic information about a key"? Does that not perform any verification of claims? Indeed, `-p` would have been the same as the current `verify`. I want to provide an option to just get info about a key, maybe even see the claims but not verify them (which consumes internet). After getting some sleep, I realize this should not be the default, so I propose a `--no-verify-claims` flag for this scenario. > verify is potentially ambiguous about whether it's verifying identity claims or signatures Yup, very much so. This is the reason I considered flag-based, but I think you're solution is quite elegant: no verb for profiles and claim verification, `verify` for signature verification, `encrypt` for encryption. > The only reason for verifying identity claims not to be the default, that I can see, is if you envisage keyoxide becoming a general purpose keyring or cryptography tool, so that verifying claims was no longer its primary purpose. I don't :) identity verification should be central and first, with sig verification and message encryption being secondary. No other functions are really planned. Creating profiles I think should be handled by a different utility (`keyoxide-gen`) or use a new verb here (`keyoxide generate` or `keyoxide create`). And yes, here's our confusion about `generation` back again...

yarmo commented 2022年03月27日 21:11:09 +02:00

In the PR #13, I'm currently trying out having three commands (profile, verify, encrypt) where profile is "default" so it's called when no command is specified.

So:

keyoxide test@doip.rocks // -> displays a profile
keyoxide profile test@doip.rocks // -> displays a profile
keyoxide encrypt test@doip.rocks ./msg.txt // -> encrypt a file
keyoxide verify signature.asc // -> verify a signed doc

In the PR https://codeberg.org/keyoxide/keyoxide-cli/pulls/13, I'm currently trying out having three commands (`profile`, `verify`, `encrypt`) where `profile` is "default" so it's called when no command is specified. So: ```bash keyoxide test@doip.rocks // -> displays a profile keyoxide profile test@doip.rocks // -> displays a profile keyoxide encrypt test@doip.rocks ./msg.txt // -> encrypt a file keyoxide verify signature.asc // -> verify a signed doc ```

caesar commented 2022年03月28日 01:18:16 +02:00

Hmm, trying out your redesign-interface branch:

• The profile verb, and the default (no verb) both seem to work like verify did before.

• The wkd: or hkp: prefix is still required. keyoxide test@doip.rocks fails with Error when fetching the profile data: Invalid URI. I still need to do keyoxide wkd:test@doip.rocks.

• The encrypt and verify commands show a message saying they're not implemented (fair enough!)

A promising start! I'd like to get rid of the requirement for those prefixes though, and mayber replace them with flags like we discussed above (or at least make them optional). The default should be to check WKD and then fall back to HKP).

Hmm, trying out your `redesign-interface` branch: - The `profile` verb, and the default (no verb) both seem to work like `verify` did before. - The `wkd:` or `hkp:` prefix is still required. `keyoxide test@doip.rocks` fails with `Error when fetching the profile data: Invalid URI`. I still need to do `keyoxide wkd:test@doip.rocks`. - The `encrypt` and `verify` commands show a message saying they're not implemented (fair enough!) A promising start! I'd like to get rid of the requirement for those prefixes though, and mayber replace them with flags like we discussed above (or at least make them optional). The default should be to check WKD and then fall back to HKP).

caesar commented 2022年03月28日 01:24:02 +02:00

I too am wondering if we could improve that terminology as well, compile a clear vocabulary so that across clients, across implementations, words have clear meaning.

Yes, that would be great. Maybe we should have a discussion on the forum.

I would definitely try to move away from the "generate a profile" terminology currently used on the web interface; like I say above, it sounds to me like it's going to help me actually create my own profile and add the claims to my keys.

Something like "check identity claims" might work, but maybe you want to keep the "profile" terminology, particularly if we're using the same in the CLI. And maybe "check" vs "verify" is confusing... 🤔

Creating profiles I think should be handled by a different utility (keyoxide-gen) or use a new verb here (keyoxide generate or keyoxide create).

I'd argue for a new verb rather than a separate tool. Maybe add-claim or create-claim, or just claim? I don't know. We have to think about what it actually does, but that's for a separate issue...

> I too am wondering if we could improve that terminology as well, compile a clear vocabulary so that across clients, across implementations, words have clear meaning. Yes, that would be great. Maybe we should have a discussion on the forum. I would definitely try to move away from the "generate a profile" terminology currently used on the web interface; like I say above, it sounds to me like it's going to help me actually *create* my own profile and add the claims to my keys. Something like "check identity claims" might work, but maybe you want to keep the "profile" terminology, particularly if we're using the same in the CLI. And maybe "check" vs "verify" is confusing... 🤔 > Creating profiles I think should be handled by a different utility (keyoxide-gen) or use a new verb here (keyoxide generate or keyoxide create). I'd argue for a new verb rather than a separate tool. Maybe `add-claim` or `create-claim`, or just `claim`? I don't know. We have to think about what it actually does, but that's for a separate issue...

caesar commented 2022年03月28日 01:29:35 +02:00

By the way, related to both this issue and the forum thread where we are discussing implementation of multiple claim methods/locations (which I will weigh in on again when I get the chance!)
You mentioned preferring the implementation in doip-rs (which I haven't looked at at all yet) to that in doip-js. I wondered if you have considered replacing the current JS-based keyoxide-cli with a Rust version based on doip-rs?

The advantage would be no need for the end user to have Node installed. Also quite probably more secure.
The disadvantage is probably a steeper learning curve for contributors (like myself) who are much more familar with JS than Rust...

I have no particular position to take either way right now, I just wondered if you've thought about it given what you said about doip-rs.

By the way, related to both this issue and the forum thread where we are discussing implementation of multiple claim methods/locations (which I will weigh in on again when I get the chance!) You mentioned preferring the implementation in doip-rs (which I haven't looked at at all yet) to that in doip-js. I wondered if you have considered replacing the current JS-based keyoxide-cli with a Rust version based on `doip-rs`? The advantage would be no need for the end user to have Node installed. Also quite probably more secure. The disadvantage is probably a steeper learning curve for contributors (like myself) who are much more familar with JS than Rust... I have no particular position to take either way right now, I just wondered if you've thought about it given what you said about doip-rs.

yarmo commented 2022年03月28日 10:28:02 +02:00

I received notifications of your replies shortly after I submitted my latest commits so I must have just been too late with the commits 🙈

With the latest commits, the prefixes are gone. keyoxide test@doip.rocks is now a valid command.

I have also updated the doip.js library to add an "automatic" mode which detects the input and tries WKD and/or HKP accordingly. So keyoxide support@gpgtools.org is now a valid command and will first try WKD before switching to HKP.

The flags --force-wkd and --force-hkp are now also a thing. I thought just --wkd or --hkp would not be significant enough. Alternatively, we could opt for --wkd-only and --hkp-only.

--hkp-server will not force --force-hkp. The use-case is where you still want to check WKD first, but when going HKP, you want to control which HKP server is contacted.

Something like "check identity claims" might work

I'd argue for a new verb rather than a separate tool. Maybe add-claim or create-claim, or just claim? I don't know. We have to think about what it actually does, but that's for a separate issue...

Agreed. We need to create a bunch of new discussions on the forum.

I wondered if you have considered replacing the current JS-based keyoxide-cli with a Rust version based on doip-rs?

Yes, and eventually, it will be done. Currently, doip-rs is far from feature-parity with doip-js so for now, I must stick with it.

Also, I do not per se prefer the Rust implementation (ok, I do but that's a different conversation!) but I prefer how I handle the configuration files (in doip-rs, static TOML files; in doip-js, functions that return a JSON document).

It shouldn't be too hard to fix that grievance in doip-js and would even allow us to share the config files between libraries!

But yeah, I need to find time to work on doip-rs and when it's advanced enough, we'll rewrite keyoxide-cli in Rust. That will be a glorious day :)

The advantage would be no need for the end user to have Node installed.

I have started some work to package keyoxid-cli in binary format for use with package managers! Just run npm/yarn run build. This produces quite a fat binary (as one would expect) but no more Node required!

Again, it's all patching until Rust comes along.

I received notifications of your replies shortly after I submitted my latest commits so I must have just been too late with the commits 🙈 With the latest commits, the prefixes are gone. `keyoxide test@doip.rocks` is now a valid command. I have also updated the doip.js library to add an "automatic" mode which detects the input and tries WKD and/or HKP accordingly. So `keyoxide support@gpgtools.org` is now a valid command and will first try WKD before switching to HKP. The flags `--force-wkd` and `--force-hkp` are now also a thing. I thought just `--wkd` or `--hkp` would not be significant enough. Alternatively, we could opt for `--wkd-only` and `--hkp-only`. `--hkp-server` will not force `--force-hkp`. The use-case is where you still want to check WKD first, but when going HKP, you want to control which HKP server is contacted. > Something like "check identity claims" might work > I'd argue for a new verb rather than a separate tool. Maybe add-claim or create-claim, or just claim? I don't know. We have to think about what it actually does, but that's for a separate issue... Agreed. We need to create a bunch of new discussions on the forum. > I wondered if you have considered replacing the current JS-based keyoxide-cli with a Rust version based on doip-rs? Yes, and eventually, it will be done. Currently, `doip-rs` is far from feature-parity with `doip-js` so for now, I must stick with it. Also, I do not per se prefer the Rust implementation (ok, I do but that's a different conversation!) but I prefer how I handle the configuration files (in `doip-rs`, static TOML files; in `doip-js`, functions that return a JSON document). It shouldn't be too hard to fix that grievance in `doip-js` and would even allow us to share the config files between libraries! But yeah, I need to find time to work on `doip-rs` and when it's advanced enough, we'll rewrite `keyoxide-cli` in Rust. That will be a glorious day :) > The advantage would be no need for the end user to have Node installed. I have started some work to package `keyoxid-cli` in binary format for use with package managers! Just run `npm/yarn run build`. This produces quite a fat binary (as one would expect) but no more Node required! Again, it's all patching until Rust comes along.

caesar commented 2022年03月29日 21:28:31 +02:00

I've just been playing with the latest version of this and it's great.

I have also updated the doip.js library to add an "automatic" mode which detects the input and tries WKD and/or HKP accordingly. So keyoxide support@gpgtools.org is now a valid command and will first try WKD before switching to HKP.

Brilliant! 👍

Not specifically related to this issue, but I would like it if the output said where the key came from – especially relevant in "auto" mode.
Something like (as the first line of the output, before the fingerprint):

• PGP key fetched using WKD from https://openpgpkey.doip.rocks
  Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b
  ...
  

• PGP key fetched using HKP from https://keys.openpgp.org
  Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b
  ...
  

• Maybe in auto mode:

  No key found using WKD for domain doip.rocks.
  PGP key fetched using HKP from https://keys.openpgp.org
  Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b
  ...
  

What do you think?
I could implement and send a PR against your PR 🤔

---

Re moving over to doip-rs, got it, that's basically the situation as I had assumed it to be. So we need to work on getting feature parity between doip-js and doip-rs.
I might have a play with doip-rs when I get a chance.

I've just been playing with the latest version of this and it's great. > I have also updated the doip.js library to add an "automatic" mode which detects the input and tries WKD and/or HKP accordingly. So keyoxide support@gpgtools.org is now a valid command and will first try WKD before switching to HKP. Brilliant! 👍 Not specifically related to this issue, but I would like it if the output said where the key came from – especially relevant in "auto" mode. Something like (as the first line of the output, before the fingerprint): * ``` PGP key fetched using WKD from https://openpgpkey.doip.rocks Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b ... ``` * ``` PGP key fetched using HKP from https://keys.openpgp.org Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b ... ``` * Maybe in auto mode: ``` No key found using WKD for domain doip.rocks. PGP key fetched using HKP from https://keys.openpgp.org Fingerprint: 3637202523e7c1309ab79e99ef2dc5827b445f4b ... ``` What do you think? I could implement and send a PR against your PR 🤔 --- Re moving over to doip-rs, got it, that's basically the situation as I had assumed it to be. So we need to work on getting feature parity between doip-js and doip-rs. I might have a play with doip-rs when I get a chance.

yarmo commented 2022年03月30日 09:50:30 +02:00

I would like it if the output said where the key came from – especially relevant in "auto" mode.

I was thinking of the same thing. In this specific case, the doip.js library handles the automatic mode but doesn't tell us where the key came from. We must update the library before the CLI.

I'll make a patch to doip.js later today. If you want, you can make the PR for the CLI (note, changing the CLI output will fail the tests...)

> I would like it if the output said where the key came from – especially relevant in "auto" mode. I was thinking of the same thing. In this specific case, the doip.js library handles the automatic mode but doesn't tell us where the key came from. We must update the library before the CLI. I'll make a patch to doip.js later today. If you want, you can make the PR for the CLI (note, changing the CLI output will fail the tests...)

yarmo commented 2022年03月30日 09:52:03 +02:00

Closed with merging of #13

Closed with merging of https://codeberg.org/keyoxide/keyoxide-cli/pulls/13