# Architecture Ideas, Sketches, and Meeting Notes

## San Diego Architecture Summit, March 2014

### Prosperity4All: Asterics webification

• An AsTeRICS model is:
• created by a user in the configuration suite (ACS) and run in the ARE (AsTeRICS Runtime Environment)
• equivalent to a solution in the GPII prefs framework - something that can be put in the solution registry and can be launched and configured
• AsTeRICS uses Apache Thrift to produce cross language bindings for doing stuff with a model - this includes:
• Finding components
• Setting properties on them
• Start/Stop model
• We (Simon Bates and the AsTeRICS team) are creating a GPII settings handler capable of using the thrift binding to:
• Configure properties of components in a model
• Stop models
• This is a settings handler specific to AsTeRICS' usage of thrift, rather than for thrift in general
• It's the model developer's job to create the solution entries with transformations between common terms and component properties
• In theory, in the moderate future we could imagine supporting generic kinds of property endpoints, perhaps via a kind of "CSS-like syntax" for targeting property categories rather than just individual properties by component id and name
• For example, it may be a general characteristic of a type of model that it supports mouse input, and the user may have registered general preferences appropriate for their mouse input requirements

• We need to find examples of personizable AsTeRICS models
• If they don't exist, we should build some examples
• Summary to the DSpace list
• Give the summary from these notes
• Validate approach with C+M and at the same time, Simon Bates will play around with it a bit more.

### Better, less broken, builds

(A.K.A npm, grunt, not dying on multiple copies of infusion)

#### Why There Can Only Be One Instance of Infusion

• Infusion provides a shared, public namespace for developers to name and expose their components
• Without a shared namespace, it will be incredibly difficult for Infusion users to be able to find and see someone else's modules at a stable place in the namespace
• A key community value is that "any action performed by one community member can be undone (or modified) by another"
• Examples of this kind of interaction between community members are:
• Use of distributeOptions via IoCSS to find and "modify" components by type throughout a component tree
• Without a single, global, shared namespace we would have nowhere to store those definitions which need to be shared across the community - for example, the registration of defaults blocks and the component creator functions which are used to construct them
• By definition, if some code is isolated, it can't be found and adapted by other people
• The standard semantic for node/commonjs modules gives each one a separate, isolated "global namespace object" and only allows references explicitly assigned to module.exports to be visible from the outside

#### The Current Bug with Multiple Instances of Infusion

Previously, npm would ensure that multiple copies of a shared dependency would never be installed on the filesystem. So for example, if both Kettle and universal depend on Infusion, npm used to ensure that only one copy of Infusion was available, and it was located at the topmost level (i.e. universal in this case). This behaviour changed at some point, and now we're getting multiple copies of Infusion, which causes the system not to work while providing only obscure and hard-to-understand errors

Two general approaches:

1. TASK GPII-88: A short term fix (Steve Githens with Simon Bates). Create a grunt script with a target called "install" that:
• runs npm install
• runs npm dedupe (or our own custom "vacuum cleaner" script)
• Antranig doesn't like the fact that npm is very slow and thinks we should have, for git-based dependencies, a custom installer as part of this grunt infrastructure
• while we're at it, we should consolidate the build, clean and run scripts across both the Linux and Windows repository using Grunt and JS, so that we don't have two separate copies of the same logic.
2. Create our own module loader

#### Issues with the current module loader

• "Mouse droppings"--the requirement for these little "kettleModuleLoader.js" files being placed anywhere where some configuration needs to refer to other modules to be loaded declaratively
• Kettle apps have configuration files describing each 'mode' in which the kettle app should run (currently linked to NODE_ENV). The config file specifies the fluid.defaults material, as well as a special block call 'includes'
• The 'modules' block declare the modules (js files) they depend on (e.g. https://github.com/GPII/universal/blob/master/gpii/node_modules/flowManager/configs/base.json#L18-L20)
• No easy way of "overlaying" third-party applications and configuration without requiring it to be located in a particular "official" repository
• TASK (COLIN) - GPII-492: Filing a bug with npm (the case: A depend on B and C, B depend on C .... Set up the 3 required repos (or at least B and C), create test case, submit request.

#### Getting GPII to work with Node 0.10.x on Windows

• Simon tried out the system on Windows with Node 0.10.x:
• MinGW updated to latest version - everything built fine without errors
• Updated node to 0.10.25, and encountered an error caused by the npm multiple infusion version issue described in the NPM notes
• got past that by deleting the infusion directory under node_modules in kettle
• Latest error that was encountered:
    11:54:13.769:   FATAL ERROR: Uncaught exception: %1 is not a valid Win32 application.

C:\Users\Simon\idrc\gpii\windows\node_modules\ref\build\Release\binding.node

(....)

• Potential solutions:
• This could be a problem with node-ffi. We might need to update node-ffi to the latest version
• this could in turn result in a new error if node-ffi has changed their API.
• TASK: SIMON will look into updating node-ffi. Binaries are hopefully available so no compiling is required. Alternatively, it might be possible to install with 'npm install'
• TASK: SIMON to create a JIRA ticket to update to Node 0.10.x

### Ontology Server

• http://issues.gpii.net/browse/GPII-672
• 3 shades of preferences in the system
• black box-style settings, ie. settings that we dont know anything about
• flat application settings
• flat Common terms

#### Why Do We Have An Ontology Server?

• We want to allow different components in the system to have different views/categorization of preferences
• A component (consumer of preferences) should be able to see their "view" of the preference set as definitive (as well as writeable), while still being interoperable with others' views

#### What Does the Prototype Ontology Server Do?

• It's semi-hardcoded to translate settings from the flat ontology to the old hierarchical ISO24751 format
• It does so by looking for patterns (registry.gpii.net) to decide what format a preferences is in.

#### What Should the Ontology Server Do?

• Provides the service of transforming between documents stored in any one ontology and another
• Store "rules" describing how one ontology relates to another ontology
• Each ontology should have a (amongst all ontologies) unique ID--Note: we need to ensure that the common terms registry supports user-defined namespaces (e.g. to distinguish between names for operators, ontologies, preferences, etc.)
• Preferences sets should consist of containers keyed by ontology IDs, for example:
    {

"http://registry.gpii.net/ontology/catOntology": {
food: {
catuODameDesuKa: false,
mango: false,
liminal: {
chickPea: "occasionally"
}
}
},

"http://registry.gpii.net/ontology/flatOntology": {
"http://registry.gpii.net/common/fontSize: {
values: [
28
]
}
}
}

• Each consumer declares what format (ontology) it wants preferences in
• Examples of consumers of preferences are - a matchmaker, a preferences editor
• A consumer is not shown preferences that cannot be represented in its ontology, but it can get a writeable view to those preferences which can be represented. This means that:
• a consumer is shown a preference if it can be accurately represented in its own ontology. They will never see those preferences that are determined--by the author of the ontology transformation--to be too low-fidelity.
• to support a writable view, each ontology transformation must be bidirectional
• What is shown to a consumer is just from the viewpoint of one ontology, it is not shown the ontology-keyed container structure held in the original preferences document
• So our example set might look like this, if
• the consumer requested the preferences set in the "catOntology."
• There is a transform from the flat ontology to the catOntology, which specifies that the term "fontSize" (in points) from the flat ontology, transforms into one of three categories "small", "medium", "big" in the catOntology:
                {
food: {
catuODameDesuKa: false,
mango: false,
liminal: {
chickPea: "occasionally"
}
},
font: "big"
}

• Implies that the ontology server is co-located with the preferences server, and there is no raw access to the persistence in the preference server unless specifically requested
• This is the same requirement as for security policy-mediated access to preferences
• no raw access, writeability, filtering of preferences
• Handling of "contexts" within preferences sets is similar
• Contexts are also ontologized, and a consumer that can't represent a context is not shown contextualised preferences
• Consumers that can't represent *any* contexts are not shown any preferences which are contextualised
• Colin has declared that "ontology names represent examples of common terms"
• Each preference will only be represented once in an NP set
• When requested to convert a preference set into a particular ontology, the request must contain: 1) a preference set 2) a target ontology, and outputs a preferences set as specified above

#### Future Issues

• What happens when a term in one ontology maps to several terms in another ontology, say:
• Ontology A: font: { size: 24, style: italic }
• Ontology B: fontStyle: "emphasized" -> This will be a naturally fuzzy transformation back to Ontology A
• should be able to find route from ontology A->Z via ontology X1, X2, ..., Xn

#### Questions

• What is API for the "preferences server" (i.e. ontology and preference server combo)
• Should the ontology server has a separate public interface (i.e. translate A from ontology X into ontology Y)

### Security and Privacy

• Security and Privacy.
• We need a means by which applications prove that they "are who they say they are"
• We think this risk is more profound when applications are making request from outside the framework on the local machine, and are doing on their own initiative, rather than being invoked by the framework
• Is "the outside" more suspicious than things on the local machine? (e.g. should we be as suspicious of a USB Listener making a REST request from localhost as we are of, say, Facebook making a request from the Web to the web-based Flow Manager)
• RISK: There are still quite profound risks on the local machine:
• There are obvious "privilege escalation attacks" available as a result of web service buses used for communication on the local machine
• In the current implementation, any process with the ability to open localhost sockets on the local machine can send arbitrary messages to the flow manager, and gain enormous powers over the configuration of the machine
• The solution seems to require some kind of "durable association" between particular preference profiles and particular accounts on the local machine, as well as some scheme for the client end of the web services bus to make assertions both about the identity of the requesting code and the user account it is running as
• The latter seems to require us to restore "real session support" for use in the local GPII system - that is, they should use a "shared secret" system which allows a request to prove that it is part of a particular session. In order to verify user account status, we could ask the client at the start point of a session to verify that it has read access to a file created with particular permissions by writing an "initial secret" to this file
• Actually, we need more than this - the originating client should actually demonstrate that they have WRITE PERMISSION to the user's file space
• The alternative to this is completely abandon local HTTP access as the primary API to the local flowManager
• We adopted this because of the difficulty of reliably compiling node addons on different platforms, especially on Windows
• We need to enumerate each part of the system and what privileges they need:

#### THREE MODELS for validating user listeners and other local processes which require to communicate with the flow manager

1. Filesystem permissions route - the flow manager "challenges" the listener to manipulate a particular file in the filesystem that is writeable only by the current user - this validates that the listener has EQUAL OR GREATER PERMISSIONS than the currently logged-on user
2. "initial shared secret" mode - in the case that the listener runs as part of the user account, it is possible that we insist that it is started by the flow manager itself - in this case the flow manager can distribute and initial shared secret to it as part of its execution arguments which need to be provided as part of every REST call back to it--the advantage to this approach is that it's much cleaner and simpler, but we're concerned that our user listeners may not support running in user space
3. In the case that the requesting process is part of a browser operated directly by the user, the browser could be required to go through a logon process via a UI resulting in a shared secret in the category of ii) of the traditional kind used for validating HTTP sessions

The PCP is an interesting sample of this problem in that it somewhat "falls between the stools" of being an "autonomous local process" and a "browser process belonging to the user". Although it will be implemented using web technologies it is more likely that it falls into the first category in that we will not want to put the user through the UI of a separate login process. Therefore it should use schemes i) or ii) - depending on whether or not we can arrange that the PCP is always started up by the flow manager.

In general we should arrange that as many as possible of the user listeners run with lower privileges, but this may be technically impossible in many cases. Also, we have the ultimate requirement (probably not achievable for quite a while) that the user listeners can be used to trigger SSO login to both a user account on the local machine as well as the local GPII infrastructure (the local flow manager). This implies that they are running with elevated privileges in any case - which again implies that we would need to use validation model i) for securing the start point of an HTTP conversation with the flow manager.

SSO login requires interacting with parts of the OS that are generally considered extremely sensitive and we should not embark on this lightly. Integration at this point will likely require cooperation with the platform vendor or infrastructure.

task: Look at existing user listeners and which ones can run in user space

#### Web-Based Application Security Example (Using BrowseAloud as the case study)

Step 0. The BrowseAloud developers submit their solution to the Solutions Registry (by declaring their solutions entry document, which must contain a list of the capabilities they support). In response, the Solutions Registry returns to them a "consumer secret/API key." This may be mediated by a web form for the Solutions Registry.

   - TASK: we should create a template that developers can easily use, containing the sorts of settings that a typical webapp might need. We should also do this for apps that use the Preferences Framework.



Step 1. A user of BrowseAloud agrees to allow it to access preferences on their behalf. This will be accomplished by having BrowseAloud redirect the user back to the GPII. The user will see a user-friendly summary of the preferences that the requesting site (i.e. BrowseAloud) want access to. It is essential to being able to provide this summary that the solution registry entry is expressed in terms of "common terms" which have been supplied with a human-intelligible description. If they have not, the system will only supply untransformed and unmediated settings that are just good for the single application (that is, it will not attempt to transform or otherwise transfer settings between different applications) If the user consents, BrowseAloud will be given a user key for this particular user.

   - BrowseAloud will store this key in a table and supply it each time it requests preferences on behalf of the user.
- These keys might be time-limited or revokable



An Aside: The Cloud-Based Flow Manager Operates in a "inverse settings handler" model, whereby applications pull settings (by making a REST call) from it, rather than having settings pushed into them (as is the case for the local Flow Manager, which launches applications rather than having applications request things)

##### On a Per-Request Basis

Step 1. Whenever BrowseAloud makes a request to the cloud-based Flow Manager, it must provide both the consumer secret and a user secret (subject to it not being expired or revoked). Step 2. In response to a request for settings, the Flow Manager will:

• fetch the user's preferences from the preference server (which will automatically apply any user security policies to the perference set). In practice, this means that the Flow Manager will only receive the preferences that the user wanted to share with BrowseAloud
• run the usual matchmaking and transformation process, passing back a list of settings in BrowseAloud's "native format"

task: Make diagram of this webapp based registration and usage of preference requests

## San Diego Architecture Summit, February 2013

### Supporting Web Applications

#### Three levels of integration

• Given URL to preferences server
• Personalization "happens for free" with UIOptions, once it is working (Requires ressurection of nodejs proxy, ressurect the accessForAll datasource and generalize it)
• Supply a transformation document which at the same time determines preferences of interest - your webapp is in the solutions registry.

#### Authorization

Auth issue is separate and orthogonal - This is handled by a portable system similar to Xavi's, which involves holding a table in which authentication tokens issued by 3rd parties (most likely via OAuth) to GPII tokens

#### Structure

We will create a new repository - gpii-web, which includes:

1. node.js proxy + (subrepo of Infusion - unless we have grunt Infusion build)
2. GPII data source
3. Eventually PHP code for WordPress etc.

#### The Double Application Issue (TM)

User risks to have a double accommodation of his/her preferences, by having eg. both Windows and UIOptions double the font size. This would require a quadrouble font size. To avoid this we'll need some ability for the 'online matchmaker' to know what has been set by the OS. This likely means that a plugin is required for the OS/browser to communicate (or rather, the local matchmaker used by the OS and online MM used by browser). To know that both browser and OS are part of the same session (and not part of the session in your Ipad at home) we'll need some sort of temporary 'device session id' (DSI)

#### 4 models for connecting a website to the GPII (identities)

1. Standard OAuth type - Face takes you to the GPII (1 time only) and GPII asks you if you want to connect the two and what portion of the preferences you want to connect. We think OAuth is capable of doing this.
2. Always make me authenticatesome kind of 2-factor authentication (like google, securecard, etc). You're given a challenge from the GPII server (transmitted to you by some means, eg. dialog, SMS, email, etc.)
3. There's a dedicated piece of hardware plugged into the computer
4. We require a browser plugin to pass DSI (to avoid double application issue), alternatively (and perhaps preferably) this could be handled by communicating via JSON payloads

#### Next Steps

1. Draw picture / Diagrams and other stuff
2. Investigate OAuth in details. Answer whether OAuth supports policies for granting access. ie. facebook can never see I'm using screenreader, but can see I need simplification.
3. Understand the ideas of the security gateway / design a robust policy system.
4. Make a webbased matchmaker and flowmanager
1. Simple webservice that can be called with user token and application ID (and various other stuff)
2. Create plugin for webbrowsers

### Open Source Governance/Commit Access/etc.

• Two github organizations; Cloud4All and GPII
1. Cloud4all: Repository governed based on the rules of the work-group implementing the functionality.
2. GPII: Repository governed based on the rules defined by the GPII community rules.
• GPII community rules: (sustainability)
• Scalability
• Public issue tracking on a reasonably granular level
• Code reviews
• Participation in community forums (incl. mailing list, IRC, Wiki and regularly attending meeting)
• Documentation
• No self pushing
• Bottom Line (Core/Help out/Don't Sweat)

### Preferences editors

• Simple one for pilots

### Other topics we discussed

• Preferences Server
• Common terms & app specific
• Device Reporters
• Settings Snapshotter
• Matchmaking
• Flat + Matchmaker
• Android
• User-Level Experience
• Installers
• System startup, etc.
• Library Use Case
• UI Options Architecture and Supporting Diverse Editing Experiences (e.g. wizards)
1. Easily extensible with new preferences
2. Full i18n/localization
3. Ability to embed portions of UIO into different experiences such as wizards
4. New designs and out-of-the-box preferences
• PMT PCP (Preferences Management Tool / Personal Control Panel)
• Security gateway
• Transformations
• Review pull requests