Data browser Open-With

A Solid data browser app has a privileged role as a default view of any resource on the pod. To provide flexibility to the data owner and enable innovation in user interfaces, a data browser app may support dynamic loading of resources either within internal panes or external apps. A generic process involves dereferencing of registered panes and apps specified in RDF within the pod. Selected realisations of the generic process are defined, namely discovery using type registrations, panes compatible with PodOS, and apps where resources are specified using uri search parameters.

Introduction

This document defines a generic process for dynamic loading of resources by an agent from RDF definitions either within internal panes or external apps. It is designed to be implemented by data browser apps with modular support for different types of panes. Selected realisations of the generic principles are then specified, including SHACL shapes where relevant.

Terminology

To be completed

pod/storage data browser app app pane

Namespaces

Prefixes and Namespaces
Prefix	Namespace
`apps`
`rdf`	http://www.w3.org/1999/02/22-rdf-syntax-ns#
`solid`	http://www.w3.org/ns/solid/terms#
`schema`	http://schema.org/
`xsd:`	http://www.w3.org/2001/XMLSchema#
`interop:`

Design

This specification aims to follow the principle of least privilege. A pod's data browser app is assumed to need access to arbitrary resources on behalf of the user in order to provide a local view or to have enough information to enable dispatching to an external app.

This specification SHOULD NOT be used by non-data browser apps, which would instead need to go through an agent which does have access to arbitrary resources.

The data browser app determines the level of control passed to internal panes. In general, external apps are responsible for managing their own authentication and authorisation.

An app or data registry associates panes with data types. The data browser app receives a uri, and dereferences the corresponding resource. It identifies an applicable pane or app in the registry via the characteristics of that resource.

The registry SHOULD allow panes and apps to be identified solely based on dereferencing the resource to be displayed.

Panes and apps are defined using a range of classes, which have realisation-specific descriptions. The data browser app interprets the pane or app description and either displays the data using the pane or dispatches to the relevant app.

Discovery profile: Type indexes

Discovery of panes and apps MAY be performed through an extension of type indexes.

As part of statements of type solid:TypeRegistration, type indexes MAY use two additional predicates:

apps:panes to specify definitions of one or more panes to use
apps:apps to specify definitions of one or more apps to use

Consider using interop:application, similar to https://pad.lescommuns.org/qfR3gwywSOWFceTBjIHPsw#New-proposal

The pane or app definitions MAY be in another document and the data browser app MUST dereference the URIs of the definitions before proceeding.

The URI of the pane or app definition MUST be trusted by the data owner and MUST NOT be publicly writable.

Panes or apps may be of a variety of classes. The daa browser app SHOULD gracefully fail on unsupported pane or app descriptions.

The SHACL shapes are relatively general:

apps:TypeRegistrationShape a sh:NodeShape;
sh:targetClass solid:TypeRegistration;
sh:property [
  sh:path apps:panes;
  sh:nodeKind sh:BlankNodeOrIRI
];
sh:property [
  sh:path apps:apps;
  sh:nodeKind sh:BlankNodeOrIRI
];

Specify that the data browser app may open resources of type schema:Product with :ProductPane or :PantryApp.

:Product a solid:TypeRegistration; 
solid:forClass schema:Product;
apps:panes :ProductPane; 
apps:apps :PantryApp.

Note that this is only a discovery mechanism. The predicates apps:panes and apps:apps do not restrict the class of :ProductPane or :PantryApp.

Discovery profile: Type registration with data registration shape validation

This whole section is still uncertain.

Discovery of apps by class may not be sufficient to establish compatibility with an app. To this end, type registrations MAY be further restricted by specifying a shape that the data registration MUST conform to.

The predicate sh:targetNode SHOULD be used to apply the shape to the type registration.

Validating the data registration itself ensures the integrity of data discovery as well as of the data, and ensures that the full tree within which a resource sits has been validated.

This discovery profile is only suitable for resources covered by type registrations. This typically excludes public resources or resources held by other data owners. The data browser app MAY fall back on discovery solely by class, optionally with a warning that validity has not been tested.

If the predicate solid:instanceContainer is used, a resource is covered by a type registration if it is of the class specfied by the type registration and by URL semantics is contained within the specified container.

If the predicate solid:instance is used, the referenced resource is covered by the type registration if it is of the specified class.

Additionally, any resource that is within the path of the specified shapes is also considered to be covered by the type registration.

Given that type indexes are intended to be high level structures like Photo Libraries, Music Libraries, Issue Trackers, a process is needed to tie the resource to the high level structure. This issue has notably been tackled by shape trees. Here, an assumption is being made that an app can handle any resource within the defined shape. That might not be appropriate.

The data browser app SHOULD ensure that the data is valid. Validation SHOULD be performed recursively, first dereferencing paths if the predicate apps:followMe is present.

apps:followMe probably better belongs in a different vocabulary. a sh:FollowMe is used by https://github.com/SolidOS/form-playground/blob/a3c472ca643ac470fe89be697d3301716bf2c372/examples/contacts-shapes.ttl#L41

:RecipesTypeRegistration a solid:TypeRegistration; 
solid:forClass schema:Recipe; 
solid:instanceContainer <path/to/cookbook/>;
apps:apps myappv1:RecipeApp.
myappv1:RecipeAppRegoShape sh:targetNode :RecipesTypeRegistration.

myappv1:RecipeAppRegoShape a sh:NodeShape;
sh:class solid:TypeRegistration;
sh:property [
  sh:path solid:forClass;
  sh:equals schema:Recipe
],
[
sh:path solid:instanceContainer;
sh:node myappv1:CookbookShape;
apps:followMe true
].

Restricting resources by shape could be supported too?

Discovery profile: SAI application registrations

This section has not yet been reviewed by an SAI expert or implementer.

The SAI specification also supports the discovery of apps and dispatching of a resource to that app. This section summarises the process documented there.

Assuming the data browser app is the data owner's SAI authorization agent, it has access to application registrations in an agent registry.

Applications define an app's data compatibility using access needs groups, consisting of access needs with registered shape trees.

The shape tree of the resource is compared and matching applications are identified.

A selected app is granted access to the resource if this has not already been done, and the resource is opened in the app by redirecting to the app's authorization callback endpoint.

Adapted from SAI

In the agent registry, the application registration links to the application as a registered agent.

alice-agents:2f2f3628
  a interop:ApplicationRegistration ;
  **interop:registeredAgent** projectron:id ;
  interop:hasAccessGrant alice-agents:2f2f3628\/27eae14b .

The app itself defines its access needs and authorization callback endpoint.

projectron:id
  a interop:Application ;
  interop:applicationName "Projectron" ;
  **interop:hasAccessNeedGroup** needs:need-group-pm ;
  interop:hasAuthorizationCallbackEndpoint projectron:redirect .

needs:need-group-pm
  a interop:AccessNeedGroup ;
  **interop:hasAccessNeed** needs:need-project .

needs:need-project
  a interop:AccessNeed ;
  interop:registeredShapeTree pm-shapetrees:ProjectTree .

Discovery profile: SAI-compatible panes

This section has not been reviewed by any SAI expert or implementer

Discovery of panes MAY be performed through an extension of SAI application definitions.

As part of statements of type interop:Application, the predicate apps:panes MAY be used.

Prior to loading the pane, the data browser app MUST ensure that an appropriate access grant exists for the application.

The pane definitions MAY be in another document and the data browser app MUST dereference the URIs of the definitions before proceeding. The URIs of the application definition and pane definition MUST NOT be publicly writable.

Panes may be of a variety of classes. The data browser app SHOULD gracefully fail on unsupported pane descriptions.

The data browser app SHOULD ensure that the pane is only provided access to triples covered by the application's access grants.

The application definition has one extra statement pointing to :ProjectPane. As noted in the previous example of apps:panes, this is only a discovery mechanism. The predicate apps:panes does not restrict the class of :ProjectPane.

projectron:id
a interop:Application ;
interop:applicationName "Projectron" ;
interop:hasAccessNeedGroup needs:need-group-pm ;
interop:hasAuthorizationCallbackEndpoint projectron:redirect;
apps:panes :ProjectPane.

App class: open a resource specified via a search param

The data browser app MAY dispatch a resource to an external app using a url of the form https://app.example.com?uri=https://storage.example.com/resource

The app definition SHOULD define the class as apps:App.

The app definition SHOULD use the predicate apps:uriPrefix

This treats the uri as an opaque string. Should terms that make the search param explicit be considered instead?

The data browser app SHOULD construct the URI using the prefix and resource URI, and navigate to the resulting URL.

The pantry app specifies the prefix to use to open the resource in the pantry app. Consistent with the design of this spec, authentication and authorisation is the responsibility of the pantry app.

:PantryApp a apps:App;
apps:uriPrefix "https://pantryapp.example.com?uri=".

Apps using SAI can be supported using resource indication with the Authorization Redirect Endpoint.

The link is to the authorization agent while specifying the client id of the app to use and resource intended to be opened.

:PantryApp a apps:App;
apps:uriPrefix "https://auth.alice.example/redirect?client_id=https%3A%2F%2Fsaipantryapp.example.com%2F%23id&resource=".

A dedicated syntax more closely aligned with SAI may be desirable, in particular to avoid hardcoding the authorization agent.

Resource validation

To be completed

The app definition MAY additionally provide a shape to validate the resource.

The app definition MAY additionally provide a shape to validate the data registration.

:PantryApp apps:typeRegistrationShape ex:RecipeRegoShape

If a shape constraint is present on both the app and the data registration (See "Type registration with shape validation"), the agent SHOULD test whether they are identical. If they are not identical, the agent MAY validate the data registration against the app shape.

Pane class: PodOS-compatible panes

Data browser apps MAY offer support for panes compatible with PodOS. These are HTML fragments using web components that receive access to a PodOS instance and a resource via events.

Pane definition

A pane definition SHOULD define the class as apps:PodOsPane

A pane definition MUST include at least one of the predicates:

apps:podOsHtmlUrl , linking to a URL that dereferences to a conforming HTML fragment.
apps:podOsHtmlText providing as object a conforming HTML fragment.

Handling of definitions with more than one HTML fragment is left to the discretion of the data browser app.

The corresponding SHACL shape states:

apps:PodOsPaneShape a sh:NodeShape;
sh:targetClass apps:PodOsPane;
sh:or (
  [
    sh:path apps:podOsHtmlUrl;
    sh:nodeKind sh:IRI;
    sh:minCount 1
  ]
  [
    sh:path apps:podOsHtmlText;
    sh:datatype xsd:string;
    sh:minCount 1
  ]
).

The product pane registered in Example 1 is defined as the HTML fragment accessible at the specified URL. Both these statements must be in the same document.

:ProductPane a apps:PodOsPane;
apps:podOsHtmlUrl <https://example.org/product-pane.html>

Pane rendering

The data browser app MUST dereference the url at apps:podOsHtmlUrl and parse it as HTML, inserting into the current page. The data browser app MUST NOT execute scripts in the dereferenced url. To minimise risk of triple injection, the agent MUST only dereference apps:podOsHtmlUrl links in the same document as the pane definition.

By default setting innerHTML does not execute script tags, but some scripting is still permitted. What risk does it pose?

If present, the data browser app MUST parse the text defined by apps:podOsHtmlText as HTML. The data browser app MUST NOT execute scripts.

The data browser app MUST listen for two events and respond by calling the callback function provided in event.detail. Web components in the HTML fragments SHOULD emit the events and use the provided objects.

pod-os:init is emitted to receive a reference to a PodOS instance
pod-os:resource is emitted to receive a reference to a resource

The data browser app SHOULD allow for lazy loading of web components, provide documentation of the supported web components, and provide an indication if unsupported web components have been used.

Does this spec need to specify a versioning or discovery mechanism for supported web components?

The data browser app SHOULD expect that vulnerabilities may be present in web components, and take appropriate measures to prevent arbitrary execution of code, e.g. using appropriate Content Security Policy (CSP), or limiting data access based on level of security auditing.

The agent SHOULD expect the pane to add triples to the RDF store, and take appropriate measures to protect against triple injection attacks and document any restrictions for pane users. For example, the agent may require whitelisting of panes beyond their inclusion in an app or data registry, or may provide an isolated RDF store for use by the pane.

The "pane" defined in this example simply shows the label for the schema:Product, using the pos-label web component defined by PodOS and provided by the data browser app. PodOS uses StencilJS, which lazy loads the web component when it is used.

:ProductPane a apps:PodOsPane;
apps:podOsHtmlText "<pos-label></pos-label>".

pos-label emits the pod-os:resource event and uses the resource it receives. Note that the code for the web component is defined by the web browser app. The pane HTML fragment does not define any additional executable code.

Security considerations

Triple injection

When loading panes, the data browser app typically provides access to an existing triple store in which resources have already been loaded. The data browser app can control what triples are pre-loaded, but some types of panes may also result in further triples being loaded. This opens the possibility of triple injection, in which malicious triples may be specified in loaded resources in order to change behaviour of the pane or seek to escalate privileges within the app.

Triples loaded by a pane should be treated using best practice user data handling, including where appropriate sanitisation, and isolation from other trusted data sources.

Executable code

Loading and processing of data in panes requires the use of executable code. This specification aims to ensure that a chain of trust is maintained when loading panes, and that new executable code in panes is avoided where possible - the data browser app and data owner retain maximal control over the source of executable code. Nevertheless, vulnerabilities in the data browser app and panes should be expected. Untrusted panes should not be used, especially on high value data, and security updates should be applied.