Support for mjs_api_access manifest member

[ghost]

Currently, there is an apiAccess setting in mjs_access_whitelist to enable API support for Windows 10 Hosted Web Apps (see #124). However, mixing access types for different platforms in the same rule could lead to problems in the future. For example, a hypothetical new platform could define an ‘all’ access type with a different meaning to the similarly named access type in Windows 10 Hosted Web Apps.

Also, it would be more clear having different manifest members to handle API access rules. That way navigation rules and API rules could also be defined independently.

[ghost]

See Enabling API Access. Note that this is preliminary documentation and might change in the future.

[kenchris]

Could you make that document actually explain what allowForWeb does?

[kenchris]

"platform": "ios;windows;android"

I would use spaces after ; and make sure the implementation justs strips whitespace (tabs, spaces etc)

"platform": "ios; windows; android"

[marcoscaceres]

why not just a space separated list?

[kenchris]

windows10 all, allowForWeb

Wouldn't it be better with something like

"winrt" - access to the windows runtime APIs
"custom" - access to custom Windows plugins
"all" - access to windows runtime APIs, Cordova APIs as well as custom Windows plugins

• Maybe I am totally misunderstanding how this actually works - anyways, that would mean that the naming currently isn't that good.

[kenchris]

@marcoscaceres works for me

[f2bo]

Some context regarding the new API access settings.

Originally, there was no support for loading the Cordova runtime and for using plugins in hosted web content. Therefore, API access was restricted to Windows 10 apps only and it was controlled by an apiAccess setting for rules in the mjs_access_whitelist section, which also controlled navigation scope and network access. Now that API access is supported for the Cordova-based apps, this approach is deprecated. We have separated navigation scope from API access. Navigation scope is now controlled by the mjs_extended_scope section.

For controlling API access, the mjs_api_access section defines one or more rules that control the level of API access available in different pages. We wanted to be granular with respect to API access instead of having a setting to globally enable API access for every page in the app. Therefore, each rule has a match attribute that specifies the set of pages for which it applies. This allows granting different levels of API access to different pages. To grant the same API access in all pages, you can always specify the match attribute as "*".

Now, each platform handles API access differently. Enabling API access means, for Cordova apps, loading the Cordova runtime and enabling the use of plugins in the hosted web content. For Windows 10 apps, it means enabling access to the Windows Runtime (all) or to APIs defined in the app package (allowForWebOnly). For Chrome apps, it means granting permissions such as 'background', 'clipboardRead', 'clipboardWrite', 'geolocation', etc. and so on.
It would be very difficult to express what it means to enable API access in a uniform way across all platforms. Instead, we separate API access rules according to platform and let the access attribute be whatever is meaningful for each platform. For example:

"mjs_api_access" : [
    { "match": "http://yourdomain.com/page.htm", "platform": "ios; android; windows",     "access": "cordova" },
    { "match": "http://yourdomain.com/page.htm", "platform": "windows10",                 "access": "allowForWebOnly" },
    { "match": "http://yourdomain.com/page.htm", "platform": "chrome",                    "access": [ "notifications", "geolocation" ] },
    { "match": "http://yourdomain.com/page.htm", "platform": "hypothetical-new-platform", "access": { "notifications" : [ "toast", "raw" ], "geolocation": "enabled" ] }
    ...
    { "match": "http://yourdomain.com/path1/*",  "platform": "windows10",                 "access": "all" },
    ...
]

BTW, allowForWeb was a typo (already fixed in the wiki article). The correct name is allowForWebOnly and is the name of the permission in the Windows 10 platform for enabling access to APIs defined in the app package.

[kenchris]

Navigation scope is now controlled by the mjs_extended_scope section.

And why not using just 'scope' as in the spec? Did you file any issue for the spec?

[kenchris]

I still fail to understand allowForWebOnly. So either I just enable all winrc API access, or just to what is defined in my app package.

So in the latter situation I would need to use a manifest.json plus and app package manifest? Why not just call it "restricted" or so.

Or am I to understand that only local files in the package can access Win RT APIs with allowForWebOnly?

Hypothetical new platform would probably not use permissions like that :-) Everyone is going away from that, and request permissions when needed instead. I would probably just make it a string for now.

{ 
  "match": "http://yourdomain.com/page.htm",
  "platform": "chrome",
  "access":  "notifications geolocation"
}

[kenchris]

The value "allowForWebOnly" indicates that only UWP APIs created by the developer and included inside the app package will be exposed.

That is one confusing name :-) I have no idea how that name makes any sense when you read the description from the documentation https://msdn.microsoft.com/en-us/library/windows/apps/dn934805.aspx

I would just call it "self-distributed", which makes a whole more sense.

[kenchris]

@boyofgreen ^

[ghost]

Navigation scope is now controlled by the mjs_extended_scope section.

And why not using just 'scope' as in the spec? Did you file any issue for the spec?

Actually, ManifoldJS does use scope. However, there are scenarios where multiple origins need to be specified in the navigation scope, and that is not allowed according to the specification of scope. mjs_extended_scope "extends" scope as an array of URL patterns (see this comment).

[boyofgreen]

This whole API thing is a messy business, but API access is what makes this extendable byond what can be done in the web.
@kenchris we do have a problem with the Windows API naming conventions. allowForWebOnly must be a very windowsie value, because it doesn't really describe what is going on. 99.99% of the time, folks will just choose "all". Truth is, if you are going to engage allowForWebOnly you need to upgrade the experience to visual studio to add the C++ or C# part anyways, so at that point your into the MS eco-system. We'll cover what needs to be done in the documentation, but in all honestly, our direction for developers will be much like Fernando posted:

"mjs_api_access" : [
    { "match": "http://yourdomain.com/page.htm", "platform": "ios; android; windows",     "access": "cordova" },
    { "match": "http://yourdomain.com/page.htm", "platform": "windows10",                 "access": "allowForWebOnly" },
    { "match": "http://yourdomain.com/page.htm", "platform": "chrome",                    "access": [ "notifications", "geolocation" ] },
    { "match": "http://yourdomain.com/page.htm", "platform": "hypothetical-new-platform", "access": { "notifications" : [ "toast", "raw" ], "geolocation": "enabled" ] }
    ...
    { "match": "http://yourdomain.com/path1/*",  "platform": "windows10",                 "access": "all" },
    ...
]

However, commonly, we'll only see this:

"mjs_api_access" : [
    { "match": "http://yourdomain.com/page.htm", "platform": "ios; android",     "access": "cordova" },
    { "match": "http://yourdomain.com/page.htm", "platform": "chrome",                    "access": [ "notifications", "geolocation" ] },
    { "match": "http://yourdomain.com/path1/*",  "platform": "windows10",                 "access": "all" },
    ...
]

And then we can put pressure on platforms to do user request access and get rid of this whole thing.