Events description on this page are from 2018-12. Other information is from 2016-11 and might be out of date.

# Admin creation flow

* Admin registrates on Beame Authorization server and gets token via email
* Additional FQDNs generated for: Authorization server, Whisperer, Matching server, Adminstration panel?
* Admin bootstraps Beame Insta Server
* Admin starts Beame Insta Server component called **Gateway Server**
* Admin (or Gateway Server?) starts Beame Insta Server component called **Authorization Server**
* Admin navigates Browser to the Gateway Server
* Gateway Server detects that admin is not set up yet
* Gateway Server proxies the connection to Authorization Server
* Authorization server displays QR, starting provisioning flow
* ... ( provisioning flow ) ...
* Authorization server receives end-of-provisioning notification and records admin

# Registration flow
* Browser surfs to customer authorization server
* Customer authorization server - does custom things to authenticate the user
* Customer authorization server sends user data (name, email, external user id) to gateway server
* Gateway server sends (via customer authorization server): URL for accessing registration server (URL has proxying token + encrypted user data)
* Browser redirects to given URL (gateway server entry point)
* Gateway server processes proxying token and sets proxying-enabler-session-cookie
* Browser redirects to given URL (gateway server which proxies to authorization service)


# Login flow

* Browser navigates to Gateway Server
* Gateway Server detects no cookie and no token and proxies the connection to login server (Authorization?)
* ... ( login flow ) ...
* ???
* Applications list is shown on the mobile device that was used to log in. Admin has additional **Admin Panel** application as possible choice.

## Events

### Signin - on page load /beame-gw/signin

* Browser connects using socket.io to origin at the following namespaces:
	* `/`
	* `/qr`
	* `/whisperer`
... (no other socket.io events here)
* ns=`/whisperer`, event=`startPairingSession`, direction: origin to browser, source: `src/pairing/whisperer.js:_makePinData()`. In browser, sets up periodic `pinRequest` from browser to origin.
	* `relay` property - selected edge (In the form of `https://XXX/control`)
	* `signature.signedData.data` - virtual host name 
	* `pin` - array of 6 numbers (probably to be played as a sound)
	* `name` - `A-B-C-D-E-F.pin.virt.beameio.net` (where `A` to `F` are numbers from `pin`)
	* `service` - gatekeeper name
	* `matching` - matching server FQDN (not "external" matching)
	* `appId` - not sure. Sample: `8f691d9eae0b99542441dcb48ca4834b`.
	* `refresh_rate`
* ns=`/whisperer`, event=`pinRequest`, direction: browser to origin. Origin replies with `pindata`.
* ns=`/whisperer`, event=`pindata`, direction: origin to browser. Fields exactly as in `startPairingSession` event above.
	* Browser
		* Browser sets up "pin virtual host".
		* Browser maintains two "pin virtual hosts" so that older pin would still work.
		* Browser connects to the `relay` specified in the `pindata` event.
		* Browser sets up `connect` listener for the relay socketio connection.
* ns=?, event=`connect`, direction: relay to browser
	* Browser sets up listeners for the following events:
		* `hostRegisterFailed` (failed to register `A-B-C-D-E-F.pin.virt.beameio.net` on the edge)
		* `hostRegistered` (registered `A-B-C-D-E-F.pin.virt.beameio.net` on the edge)
		* `data`
		* `disconnect`
	* Browser sends `register_server` to relay. Relay sets up virtual host.
* ns=?, events=`hostRegistered`, direction: relay to browser
	* Browser displays and starts playing pin
* ns=?, event=`data`, direction: relay to browser. Two types of messages are handled:
	* `direct_mobile`
	* `done` - calls `public/js/virt_host_controller.js:initComRelay()`
* ns=?, event=`data`, direction: relay to browser (mobile via relay to browser), condition: sound pairing
	* event fields: `type`=`done`


...
* Browser invents virtual host ID `vUID` (using global variable `VirtualHostSuffix` which is `.virt.beameio.net`)
* ns=`/qr`, event=`browser_connected`, direction: browser to origin
	* event data contains virtual host name ending with `.virt.beameio.net`
* ns=`/qr`, event=`relayEndpoint`, direction: origin to browser, source: `src/pairing/qr_messaging.js:_signBrowserHostname()`.
	* `imageRequired` (boolean)
	* `data` - selected edge hostname
	* `signature.signedData.data` - virtual host name
	* `service` - gatekeeper name
	* `appId` - not sure. Sample: `8f691d9eae0b99542441dcb48ca4834b`.
	* `matching` - matching server FQDN (not "external" matching)
	* `delegatedLogin` (may be null)
	* `refresh_rate`
* ns=`/control`, event=`register_server`, direction: browser to edge
	* `payload.hostname` - random virtual host name ending with `.virt.beameio.net`
	* `payload.signature` - hostname signature of the origin
	* `payload.type` - `"HTTPS"`
	* `payload.isVirtualHost` - `true`
	* `payload.recovery` - `false`
* ns=`/control`, event=`register_server`, direction: browser to edge
	* `payload.hostname` - 6 numbers with dashes virtual host name ending with `.pin.virt.beameio.net`
	* `payload.signature` - hostname signature of the origin
	* `payload.type` - `"HTTPS"`
	* `payload.isVirtualHost` - `true`
* ns=`/control`, event=`hostRegistered`, direction: edge to browser
	* `Hostname` - random virtual host name ending with `.virt.beameio.net`
* ns=`/control`, event=`hostRegistered`, direction: edge to browser
	* `Hostname` - 6 numbers with dashes virtual host name ending with `.pin.virt.beameio.net`
...
* ns=`/qr`, event=`virtSrvConfig`, direction: browser to origin
	* event data contains virtual host name ending with `.virt.beameio.net`
* ns=`/qr`, event=`startQrSession`, direction: origin to browser, source: `src/pairing/qr_messaging.js:onQrBrowserConnection():on "virtSrvConfig"`
	* `refresh_rate`
	* `service` - gatekeeper name
	* `matching` - matching server FQDN (not "external" matching)
	* `appId` - not sure. Sample: `8f691d9eae0b99542441dcb48ca4834b`.
* ns=`/qr`, event=`pinRequest`, direction: browser to origin
* ns=`/qr`, event=`pinRenew`, direction: origin to browser, source: `src/pairing/qr_messaging.js:_setNewOTP()`
	* `data` - Sample: `521775645524300654758390`
	* `relay` - selected edge
	* `UID` - random virtual host name ending with `.virt.beameio.net` (seen before)
* ns=`/qr`, event=`QRdata`, direction: browser to origin, source: `public/js/qr.js`. *Warning: does not seem to be handled at origin at all*.
	* `relay` - selected edge server
	* `PK` - public key of the browser
	* `UID` - virtual host name ending with `.virt.beameio.net`
	* `PIN` - Sample: `521775645524300654758390`
	* `TYPE` - `PROV` or `LOGIN` (observed)
	* `TIME` - Unix timestamp in milliseconds (current clock in the browser)
	* `REG` - The string `"login"` (observed) or some other data, internally called `reg_data`
	* `appId`
* Browser displays QR with the data from `QRdata` above


# Central login flow

## Events

### Central login - on page load

* Browser connects using socket.io to origin at the following namespaces:
	* `/`
	* `/beame_login` (source: `public/js/beame_login.js`)
* ns=`/beame_login`, event=`startPairingSession`, direction: origin to browser, source: `src/pairing/beame_login.js:_buildDataPack():_buildPack()`
	* `relay` property - selected edge (In the form of `https://XXX/control`)
	* `signature.signedData.data` - virtual host name 
	* `pin` - array of 6 random numbers
	* `name` - `A-B-C-D-E-F.pin.virt.beameio.net` (where `A` to `F` are numbers from `pin`)
	* `service` - gatekeeper name
	* `matching` - matching server FQDN (not "external" matching)
	* `refresh_rate`
	* `appId` - `"beame-login"`
	* `loginServers` - `"none"`
	* `delegatedLogin` - `null`
* ns=`/control`, event=`register_server`, direction: browser to edge
	* `payload.socketId` - `null`
	* `payload.hostname` - 6 numbers with dashes virtual host name ending with `.pin.virt.beameio.net`
	* `payload.signature` - hostname signature of the origin
	* `payload.type` - `"HTTPS"`
	* `payload.isVirtualHost` - `true`
* ns=`/beame_login`, event=`pinRequest`, direction: browser to origin
* ns=`/beame_login`, event=`pindata`, direction: origin to browser, source: `src/pairing/beame_login.js:_buildDataPack():_buildPack()`. Same info as in `startPairingSession` event above.


# Service usage flow

* Browser navigates (or more likely is redirected) to the Gateway Server
* Signed token is detected (if it's not in cookie, put it into cookie on reposonse) and validated
* Application ID or URL is extracted from the token
* Connection is proxied to the appropriate service

# Insta server management flow

( Based on service usage flow )

* Browser navigates (or more likely is redirected) to the Gateway Server
* Signed token is detected (if it's not in cookie, put it into cookie on reposonse) and validated. Token contains special "is admin" flag.
* Application ID or URL is extracted from the token
* If "is admin" flag is set, connection can be proxied to the admin panel if requested


# Open issues

* Package?