Personium App

Overview

Personium interface is basically REST API based and does not provide any GUI tools. However, it is better to provide GUI tools to end-users.

Personium Project has implemented several sample GUI tools to demonstrate the functions of Personium. App developers are free to modify the published sample GUI tools.

However, Personium App developer should note that other Personium App developers are involved in this open ecosystem. Therefore, it is inevitable that all of us should follow certain basic developer guidelines (Likewise for any other OSS communities).

Video Demonstrations

1. Data Synchronization
   

2. Data ACL Management
   

Types of Personium App

In Personium, App is categorized according to the level of permission of APIs the App can use. There are basically 3 types of Apps. For details on how APIs are categorized, please refer to the Personium Concepts.

1. General Apps
2. Cell Management Clients
3. Unit Management Clients

In the following sections, definitions and deployment procedures for the above GUI types will be explained.
For detailed deployment procedures, please check out each repository's "How to deploy" section.

1. General Apps

General App is a Box level GUI that can perform operation on data contained in a dedicated Box which is only accessible to the corresponding App.

App developer designs what kind of data (files, DB, etc.) must be installed onto the user's Cell to provide services on the Personium Platform.
Most App developers implements Apps in this category.

Merits

Both App users and developers can benefit from this arrangement.

• App user (data subject)

  • All data is contained in the App user's PDS (Personium Cell) while a variety of services can be used.
  • The user can reduce the risk of information leakage by customizing the access control configurations of the data provided to the service provider.

• App developer (service provider)

  • Since data management and access control are already performed by the App user, the App developer only need to provide minimal data management on the service side.
  • The App developer can ask for permission to access data which is created by other Apps.

  An easy way to conduct marketing research or survey.

Examples

All source codes are available on GitHub.

• Minimal App - Personium's Hello World App
• MyBoard - Provide data access control using Role only
  • Demo available on YouTube
    
• Calorie Smile Sync - Synchronize data from another Web service and provide data access control using Relation and Role
• Personal Data Brokering (Wakaba Municipal Information Bank)
  etc

How to deploy an App and provide service

In this section, we will explain the basic rules and recommendations on setting up an repository. By following these rules and recommendations, it makes deploying the Personium App on Personium Cell easier.

A simple example is available.

Folder structure

The following diagram shows the folder structure of a very simple Personium App.

Calorie Smile Sync has a more complicated bar folder.

│  launch.json
│  profile.json
│  relations.json
│  roles.json
│  
├─bar
│  └─00_meta
│          00_manifest.json
│          90_rootprops.xml
│          
├─doc
│      
├─icon
│      
├─locales
│  ├─en
│  │      profile.json
│  │      
│  └─ja
│          profile.json
│          
└─src
    └─html
        │  app.html
        │  
        ├─css
        │      common.css
        │      
        ├─Engine
        │      getAppAuthToken.js
        │      
        ├─img
        │      github.png
        │      
        ├─js
        │      app.js
        │      common.js
        │      common_personium.js
        │      
        └─locales
            ├─en
            │      common.json
            │      glossary.json
            │      
            └─ja
                    common.json
                    glossary.json

Explanation and deployment procedures

#	Resource (Folder/File)	Description
1	bar	Contains definitions and contents needed to create a BAR file which will be installed as Box onto the user's Cell. Compress (zip) this folder and name the compressed file with a ".bar" extension.
2	icon	Icon to be displayed in HomeApp.
3	launch.json	Contains information used by the HomeApp to lauch the app. Sample file has entry that allow launching native App (Android/iOS) which will be supported in the near future.
4		Defaults to be used when the App developer decides not to provide multilingual support.
	profile.json	Contains information (Name/Description/Images, etc.) about the App. (Sample file)
	relations.json	Contains display name, description and image of the relation(s) defined by the App. If relation is not defined, write a JSON file with an empty hash.
	roles.json	Contains display name, description and image of the role(s) defined by the App. If role is not defined, write a JSON file with an empty hash. If role is defined, write necessary information. (Sample file)
5		Multilingual files of the App
	locales/en/*.json	English version
	locales/ja/*.json	Japanese version. (Sample file)
6	src/android	Source codes for Android App.
7	src/html	Source codes for mobile browser App. Usually can be deployed on a Web server.
8	src/ios	Source codes for iOS App.

2. Cell Management Clients

Cell Management Client is the GUI tool for managing Cell.

Cell level APIs allow administrative operations to be performed on the Cell.
For details, see here.

Functions

The Cell management client provides the following functions.

1. Data management through Cell management authority (root)
2. Registration/Modification of Cell control objects such as account and Role, or user profile
3. Register relationship with other Cell, request registration by message (like typical friends registration)
4. After relation registration, access data in another Cell that is permitted to access
5. Installation of a Box (data structure) attached to an App
6. Launch an App
7. Send and receive messages not associated with Box

The following functions are under planning.

1. App usage data privilege management, BOX uninstallation
2. Cell data explorer
3. Implementation of native App
4. Automated Cell URL input by QR code, NFC etc.
5. Configuration of user defined event, browsing of trigger log

Sample Apps

1. HomeApp Repository
   • Overview
   • Demo with tutorial
   • Demo

3. Unit Management Clients

Unit management clients are Unit level management tools that helps you manage Personium cell(s).

1. Unit/Cell Manager
   
2. Cell Creator Wizard
   
3. PCUI

The above management tools require a special token (issued by the corresponding UnitAdmin Cell) which possesses Unit management permission. Therefore, the following information is required during user authentication.

1. Personium Unit URL
2. UnitAdmin Cell name (Specified in the Personium Unit's UnitConfig file)
3. UnitAdmin account name
4. UnitAdmin account password

How to deploy

Similar to HomeApp, Unit/Cell Manager can also be deployed on a normal Web server instead of a Personium Cell.

We are also considering to build our next version of management tool in Electron.

App authentication

In the Personium Apps ecosystem, in order to defend against unauthorized phishing Apps against PDS, App authentication must be enabled for the Box defined by the same App.

App authentication means that the App that accesses the data must be authenticated by the App Cell in addition to the User's Cell authentication, and see here for details.

When the App developer cannot start the App from the HomeApp properly, in order to access the Box, it is necessary to separately acquire a token after App authentication.

Note:　App authentication is planning to support multiple schemas (implement URL hash).

Source codes based example is available here.