[Documentation] How should "internal" permissions be avoided?

[Olf0]

The header of the second table in the section "Permissions" of the README currently states: "Internal permissions that applications generally should not use directly:"

The list of "internal permissions" cover many functionality which are commonly in use (e.g., Notifications or Sharing), plus some functionality which Jolla strongly promoted (e.g., Secrets and the again overhauled sharing API).

Hence my question is: How does Jolla envision to avoid using these "internal" permissions for third party apps, while keeping the extant functionality of an app intact, including the use of Notifications, Jolla's recent Sharing API and the Jolla-Secrets API?

I would appreciate much, if the documentation is updated to clarify this and to provide some guidance what app developers should do (because that is the purpose of this documentation, IMO).

Side note: Most of the entries in the second column of the "internal permissions" table in the section "Permissions" of the README currently states are empty. It is impossible to derive the exact scope of a SailJail permission only by its name, hence filling these voids would be very helpful, because one may over-interpret the scope of a permission without a description.

Side note 2: I do not really comprehend what the current description of the Compatibility permission (in the aforementioned table of "internal permissions") is trying to denote; its appears to be a bit convoluted. Maybe it can be rephrased to be more concise (or comprehensive, if a detailed explanation is deemed necessary), when writing descriptions for the permissions without one.

[attah]

I'll attempt an explanation: Not all are internal as in internal use only, but library permissions included by ones that you are allowed to use. Specifically Notifications and Sharing are definitely of that kind. I.e. the vision is to (only have to) use derived permissions. Using those not yet included in other permissions (if any - would be good to know) is "not supported" i assume.

Compatibility was added for me, Poetaster and some others that got creative and skirted harbour rules with calling binaries in QProcess. It really doesn't do more than allow access to some select binaries: https://github.com/sailfishos/sailjail-permissions/blob/master/permissions/Compatibility.permission

[Olf0]

I'll attempt an explanation:

Thank you for your explanations. Actually they depict to bigger gaps in the documentation than I originally assumed when I created this issue.

Not all are internal as in internal use only, but library permissions included by ones that you are allowed to use. Specifically Notifications and Sharing are definitely of that kind.

IMHO "library permission" is a new term, which is not used anywhere else yet. I think it is misleading, as it is seems to be completely unrelated to software libraries (i.e., a set of callable functions), e.g., shared objects / DLLs.

But I do understand now, that the Sharing permission is part of the Base permission, which aggregates multiple permissions, as @rainemak recently pointed out. Unfortunately this is not documented in the documentation.

I.e. the vision is to (only have to) use derived permissions.

"Derived permissions" is another new term, which I completely fail to understand what it is supposed to mean. If you are trying to address what you called "library permission" before (but why would you use another new term, if it is supposed to mean the same?) and what I prefer to call "aggregated permission" (such as the Base permission), this is rather the opposite of "derived".

Note that most of the "Permissions that applications may use" (i.e., those listed in first table in the section "Permissions") are not "aggregated permissions".

Using those not yet included in other permissions (if any - would be good to know) is "not supported" i assume.

Your phrase "those not yet included in other permissions" appears to address all the "non-aggregated" permissions. I currently do not see that it would make sense to make most of these only accessible through "aggregated permissions".

But what "not supported" means, i.e., to document what the consequences of using "not supported permissions" (= "internal permissions, not to be used directly") are, is a main point of this issue. Unfortunately your explanations and assumptions did not provide any insight to this.

Compatibility was added for me, Poetaster and some others that got creative and skirted harbour rules with calling binaries in QProcess. It really doesn't do more than allow access to some select binaries: https://github.com/sailfishos/sailjail-permissions/blob/master/permissions/Compatibility.permission

To link to the source code which defines a permission in its description (i.e., for all permissions in the right left _{(better there IMO)} column of either of both tables) would indeed be very helpful, because the documentation cannot cover all the details. But the documentation should provide a brief description of each permission, its relation to other permissions (if any exists) and a link to the source code defining this permission. Documentation which requires one to read the source code immediately (because it does not document things) is useless.

Still I wonder if the bold statement (second sentence of the current description for the Compatibilitypermission), "Direct use of binaries should be avoided." really holds true (i.e., no calls of shell scripts etc.); if it does, an assertion is usually much easier to comprehend, i.e. here, "In general, only library classes and functions are allowed to be used."

Hence a first try to improve the description of the Compatibility permission might look like this:

Allows for accessing certain binaries to provide some degree of compatibility for extant apps. In general, only library classes and functions are allowed to be used by new applications. The access to these binaries may disappear in any Sailfish OS release, especially if official APIs with similar functionality are provided.

Summary

Nevertheless, the two main points of this issue are: What are the consequences of directly using "internal permissions, not to be used directly" and how does Jolla envision for developers to avoid this, if one of these "internal" permissions is technically needed (e.g., the Jolla-Secrets API)?

The most important side aspect is: Please fill out the many missing permission descriptions in the second table "internal permissions".

Enhancing the current description of the Compatibility permission is only a secondary side aspect.

[attah]

Throwing away a longer answer, i should make dinner instead...

To summarize my viewpoint: My working understanding (solidified on the community meeting) is that Jolla's vision does not include other app sources than Harbour, and trying to insert them into that vision will be a constant source for confusion. Thus SailJail (and its documentation) only really must be good enough for what is allowed there - the rest is basically a bonus.

[Olf0]

To summarize my viewpoint: My working understanding (solidified on the community meeting) is that Jolla's vision does not include other app sources than Harbour,

That was one of my ideas how Jolla may model this, until rainemak stated, "You're failing to understand different aspect of this. What is allowed in Harbour is not everything and all should documented.", and flypig created this generalisation for the documentation.

and trying to insert them into that vision will be a constant source for confusion.

This is why I am asking Jolla to document their scope and goals more clearly; otherwise the confusion will persist for app developers. As a matter of fact there are other app sources than the Jolla Store ("Harbour"); e.g., OpenRepos is much larger than the Jolla Store (in terms of downloads and offered apps).

[llewelld]

Thanks @Olf0 and @attah for the useful input, and also @rainemak for the suggestion and prompting. I've proposed an update to the description of the Sharing permission in https://github.com/sailfishos/sailjail-permissions/pull/129. This isn't intended to address all of the concerns here, but hopefully at least makes this one point clearer in the docs.

I've created an internal task to fill out the rest of the entries too, so hopefully we can get those done over time.

[Olf0]

… the description of the Sharing permission in #129. … I've created an internal task to fill out the rest of the entries too, so hopefully we can get those done over time.

Thank you very much, though both are just the part of the major side aspect, our discussion here has been slipping into. A secondary side aspect is to clarify current description of the Compatibility permission, for which I just created PR #130.

But the principal aspect still is "How should "internal" permissions be avoided?"

Which I originally described as: "How does Jolla envision to avoid using these "internal" permissions for third party apps, while keeping the extant functionality of an app intact, including the use of, e.g., the Jolla-Secrets API?"

My rephrased, more comprehensive description was: "What are the consequences of directly using "internal permissions, not to be used directly" and how does Jolla envision for developers to avoid this, if one of these "internal" permissions is technically needed (e.g., the Jolla-Secrets API)?"

[Thaodan]

My rephrased, more comprehensive description was: _"What are the consequences of directly using "internal permissions, not to be used directly"

Internal permissions as in those that used by other permissions to reuse parts that are the same between multiple permissions. E.g. permissions A uses internal permission B, permission C does the same. If internal permission B wouldn't exist there would be duplication in A and C.

and how does Jolla envision for developers to avoid this, if one of these "internal" permissions is technically needed (e.g., the Jolla-Secrets API)?"_

The APIs name is Sailfish-Secrets not Jolla-Secrets. I would say the the word internal is wrong in this case, yes the permission isn't supposed to be used e.g. not allowed in Harbour but that is not because it should only be used indirectly but because the API isn't stable enough for Harbour. Apps that still want to use Sailfish-Secrets API while sandboxed of course have to use the permission.

[Olf0]

[For] Sailfish-Secrets I would say the the word internal is wrong … Apps that still want to use Sailfish-Secrets API while sandboxed of course have to use the permission.

Well, this supposedly also applies to the Sailjail-permissions UDisks, UDisksListen and a couple of the ones which currently lack a description, as e.g., GnuPG.

Do you have an idea how to rephrase the misleading / wrong sentence introducing this second table, "Internal permissions that applications generally should not use directly:"?

Or you you think the second table should rather be split into two, one labelled "Internal permissions, used by other permissions. Hence applications generally should not use these internal permissions directly:" (and document in their descriptions, which aggregated permissions utilise them) and another one called "Unstable permissions, using them for applications submitted to Harbour is currently not allowed:"?

[Thaodan]

It really doesn't do more than allow access to some select binaries: https://github.com/sailfishos/sailjail-permissions/blob/master/permissions/ Compatibility.permission

RPM is in that list to allow to query packages but should be replaced by packagekit in a read-only fashion.