Privacy/Reviews/F1A
Document Overview
| Feature/Product: | Client-Based F1 |
| Projected Feature Freeze Date: | 1-Oct-2011 |
| Product Champions: | Shane Caraveo |
| Privacy Champions: | Sid Stamm |
| Security Contact: | Curtis Koenig |
| Document State: | [NEW] documenting |
Timeline:
| Architectural Overview: | (date TBD) |
| Recommendation Meeting: | (date TBD) |
| Wrap-up Meeting: | (if necessary) |
Architecture
In this section, the product's architecture is described. Any individual components or actors are identified, their "knowledge" or what data they store is identified, and data flow between components and external entities is described.
The main objective of this feature/product is: to enhance the sharing experience of the browser, Firefox, when sharing web sites. F1 streamlines the process of sharing by integrating various share techniques with the browser experience itself.
This release, to be named Firefox Share (alpha), is being thought of as a Labs release of F1 and not ready for prime time releases. Our goal is to get an extension out that we can start getting UX feedback from users and start iterating quickly on features and UX.
The initial release will not be extensible, but we intend to follow up early Q4 with a version that supports extensibility via OpenWebApps services (such as the Status.net addon we have created). While we have not defined Q4 goals yet, it is probable that a beta release for a wider audience, with extensibility, will be in those goals. It is also highly possible that fx-share-addon will merge with the OWA jetpack.
Design Documents: Link to any design or architectural documents here.
- Labs/F1/AlphaPlan
- Web Activities
- File:Owa-f1.pdf Data flow of openwebapps, f1 mediator and web activities (updates images below)
The following illustrates how data flows through the system when talking about mediated web activities such as F1.
Other Resources
- additional details may also be found in the Security/Reviews/F1_(round_2)
Components
Currently four jetpack based addons are bundled together as a single add-on. While the architecture of the system is slightly more nuanced, these are the main basic components:
- Mediator content iframe
- 3rd party webapps
- Mediator class
- OWA core
- Mediator content iframe
- future ability for general web content to open activity mediators
- fx-share-addon
- share mediator based on top of OWA
- new smtp module for sending emails
- 3rd party webapp
- 3 built-in apps for twitter, facebook and gmail
- future apps loaded from 3rd party sites
- mediator class
- manages mediator panel (UI)
- manages interaction between mediators and OWA core
- manages interaction between services and OWA core
- manages interaction between mediators and services
- OWA core (OWA stuff in dataflow image)
- manages apps, installation, dashboards, store interaction, etc
- most utility disabled
- dependencies
- oauthorizer
- jetpack based addon that provides api's to use oauth 1 & 2
- required for built-in apps named above
- openwebapps jetpack addon
- fx-share-addon requires openwebapps to work
- addon-sdk fork
- for has patch from bug 675812 which fixes panel style for osx
- oauthorizer
Mediator content iframe
F1 is an implementation of a mediator for the share activity. The mediator content iframe is content loaded locally from the addon. APIs (navigator.mozApps.mediator.*) are injected by the mediator class. Communication between the content iframe and the mediator class are through sdk ports, passing JSON data.
Stored Data:
The mediator stores no data.
Communication with 3rd party webapp components
Communication with third party webapps is tunneled through the mediator class. There is no direct conduit between the mediator content and the service content (even though the mediator content could directly access the service iframe).
In order to tunnel a call into a service: the mediator content emits a owa.mediator.invoke port message that contains the data necessary to complete the calls below, along with string id's that the service iframe uses to send a response back. To send a response, the service iframe will emit an owa.mediation.success.# or owa.mediation.error.# with the response data.
The mediator content initiates most of (all?) the communication with the third party webapps.
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | return from getParameters | parameter information for ui configuration and oauth | |
| return from getShareTypeRecipients | abbreviated contact data for autocompletion support | ||
| return from resolveRecipients | success/error of recipient validation | ||
| return from getLogin | user profile on success | ||
| confirm (2) | success/error of send | ||
| Out: | getShareTypeRecipients | type of share (e.g. direct, public, group name) | |
| resolveRecipients | list of recipients user has entered into TO field | ||
| getLogin/getCredentials | none | ||
| setAuthorization | oauth credentials | ||
| confirm | page data(3) | called when the user clicks "send" | |
| logout/clearCredentials | none |
1. if getLogin returns nothing, the login flow is initiated. If the login type is oauth (defined in the webapp), openwebapps initiates the oauth flow to get the credentials, and passes them to the webapp via the setAuthorization call.
2. confirm is only called when the user clicks "send" in the chrome based UI.
3. page information such as URL, opengraph data, Title, select share image (currently the first one found), etc.
Communication with mediator class
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | owa.app.ready | origin | one call for each service iframe, received after the service iframe has called owa.service.ready |
| In: | owa.mediation.setup | activity object, services list, caller href | data necessary to setup the mediator UI and load service iframes |
| Out: | owa.mediation.ready | none | called by mediator content after load is finished |
| Out: | owa.mediation.sizeToContent | width,height | request the mediator class to resize the panel to fit the content |
| In: | owa.mediation.onLogin | authorization credentials if any (e.g. oauth user tokens) | response from doLogin |
| Out: | owa.mediation.doLogin | auth configuration received from service iframe, may contain consumer oauth key/secret | requests mediator class to manage logging in for a service |
| Out: | owa.success | none | sent upon successful send |
| Out: | owa.failure | failure message | sent upon failure to send |
| In: | owa.mediation.reconfigure | none | sent to mediator content to reconfigure (e.g. a share app was installed or removed) |
3rd party webapp component
For each installed service that supports a given activity, the mediator content creates an iframe. The mediator class then injects APIs into the service iframe using the addon-sdk worker class.
Currently, F1 does not allow installation of remote services. It installs three services that are contained in the addon, Twitter, Facebook and GMail.
Stored Data:
While a service may store any data it wants in localStorage, these are the data that our implementations store.
| What | Where |
|---|---|
| user profile | localstorage |
| users contacts | localstorage |
| users oauth credentials, secrets, etc | localstorage (see oauthorizer component) |
Communication with mediator content iframe
Communication with mediator content is tunneled through the mediator class. There is no direct conduit between the mediator content and the service content (even though the mediator content could directly access the service iframe).
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | getParameters | none | |
| Out: | getParameters | parameter information for ui configuration and oauth | |
| In: | getShareTypeRecipients | type of share (e.g. direct, public, group name) | |
| Out: | getShareTypeRecipients | abbreviated contact data for autocompletion support | |
| In: | resolveRecipients | list of recipients user has entered into TO field | |
| Out: | resolveRecipients | success/error of recipient validation | |
| In: | getLogin | none | |
| Out: | getLogin/getCredentials | user profile on success | |
| In: | setAuthorization (1) | oauth credentials | |
| Out: | setAuthorization | none | |
| In: | confirm (2) | page data(3) | called when the user clicks "send" |
| Out: | confirm | success/error of send | |
| In: | logout/clearCredentials | none | |
| Out: | logout/clearCredentials | none |
Communication with mediator class
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | service.origin | origin | provides the app origin the code we inject into the service iframe, kind of an init for our injected code |
| Out: | service.origin | none | |
| In: | service.ready | none | |
| Out: | service.ready | app origin | same as origin in postMessage api |
| In: | service.registerHandler | none | |
| Out: | service.registerHandler | origin, activity and message | all strings used by mediator to call a specific handler (e.g. url, "link.send", "confirm") |
| In: | oauth.call | results returned by call to oauth endpoint | |
| Out: | oauth.call | auth service information, user tokens, url to oauth endpoint, parameters (share data) | for oauth call which are sent to oauth endpoints |
| In: | sendEmail.call | simple success/failure object | |
| Out: | sendEmail.call | user oauth tokens, share data, recipients list |
mediator class
The mediator class serves two purposes; 1) managing the mediator panel and mediator APIs, 2) acting as a tunnel between the service iframes and the rest of the OWA system.
Stored Data:
The mediator class stores no data.
Communication with mediator content
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | owa.app.ready | none | |
| Out: | owa.app.ready | origin | one call for each service iframe, received after the service iframe has called owa.service.ready |
| In: | owa.mediation.setup | none | |
| Out: | owa.mediation.setup | activity object, services list, caller href | data necessary to setup the mediator UI and load service iframes |
| In: | owa.mediation.ready | none | called by mediator content after load is finished |
| Out: | owa.mediation.ready | none | no response to ready, rather a setup message it emitted. |
| In: | owa.mediation.sizeToContent | width,height | request the mediator class to resize the panel to fit the content |
| Out: | owa.mediation.sizeToContent | none | |
| In: | owa.mediation.onLogin | auth configuration received from service iframe, may contain consumer oauth key/secret | requests mediator class to manage logging in for a service |
| Out: | owa.mediation.doLogin | authorization credentials if any (e.g. oauth user tokens) | response from doLogin |
| In: | owa.success | none | sent upon successful send |
| Out: | owa.success | none | |
| In: | owa.failure | failure message | sent upon failure to send |
| Out: | owa.failure | none | |
| In: | owa.mediation.reconfigure | none | |
| Out: | owa.mediation.reconfigure | none | sent to mediator content to reconfigure (e.g. a share app was installed or removed) |
Communication with service iframes
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | service.origin | none | |
| Out: | service.origin | origin | provides the app origin the code we inject into the service iframe, kind of an init for our injected code |
| In: | service.ready | app origin | same as origin in postMessage api |
| Out: | service.ready | none | |
| In: | service.registerHandler | origin, activity and message | all strings used by mediator to call a specific handler (e.g. url, "link.send", "confirm") |
| Out: | service.registerHandler | none | |
| In: | oauth.call | auth service information, user tokens, url to oauth endpoint, parameters (share data) | for oauth call which are sent to oauth endpoints |
| Out: | oauth.call | results returned by call to oauth endpoint | |
| In: | sendEmail.call | user oauth tokens, share data, recipients list | |
| Out: | sendEmail.call | simple success/failure object |
OWA stuff
OpenWebApps provides the ability for content to install an "app" which may also include a "services" component using the Web Activities APIs. fx-share-addon relies on the Web Activities/services functionality for extensibility.
- currently we have disabled all UI and ability to externally install any web apps.
- Only the fx-share mediator UI is available to the user.
- Web content does not have the ability currently to instantiate the share mediator, only UI in chrome (the share button in the url bar) can show the UI.
Stored Data:
| What | Where |
|---|---|
| manifest data for apps | sqlite database |
Communication with Component Y
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | message 1 | types of data received from component Y with the message | |
| Out: | message 2 | types of data sent to component Y with the message |
oauthorizer
OAuthorizer provides simple APIs for initiating OAuth login/authorization flow and calling OAuth version 1 and 2 based APIs. In our use of oauthorizer, a service iframe makes a call which is received by the mediator class. The mediator class passes that to oauthorizer which makes the oauth call and returns the response.
- future changes
- remove ability to store credentials completely
- remove content-available API and make available only to mediated openwebapps
Stored Data:
While oauthorizer can be used to store OAuth credentials, in our use it does not.
Communication with Component Y
| Direction | Message | Data | Notes |
|---|---|---|---|
| In: | message 1 | types of data received from component Y with the message | |
| Out: | message 2 | types of data sent to component Y with the message |
User Data Risk Minimization
In this section, the privacy champion will identify areas of user data risk and recommendations for minimizing the risk.
Alignment with Privacy Operating Principles
In this section, the privacy champion will identify how the feature lines up with Mozilla's privacy operating principles.
See Also: Privacy/Roadmap_2011#Operating_Principles:
Principle: Transparency / No Surprises
(How the feature addresses this)
Recommendations: (what can be improved)
Principle: Real Choice
Recommendations:
Principle: Sensible Defaults
Recommendations:
Principle: Limited Data
Recommendations:
Follow-up Tasks and tracking
| What | Who | Bug | Details |
|---|---|---|---|
| [NEW] Initial Overview Discussion | ? | Meeting time TBD |