CloudServices/Notifications/Bipostal

Overview

BrowserID Postal (BIPostal) provides a semi-anonymous method for BrowerID consumers to safely communicate and control communcations with third parties (e.g. webapp providers).

Engineers Involved

jr conlin

Terminology

BrowserID - Passwordless credential system based off of Verified Email.

Host - The site/service providing the BIPostal service.

Customer - Authorizing human being. There is a presumed level of existing trust between

Token - A randomized 256bit number converted to an appropriate base character representation.

Webapp - Third party webapp; semi-trusted party the Customer wishes to connect to through Host.

Use Cases

email notification

A Customer wishes to purchase a WebApp. The user does not wish to share their current master email with WebApp, so a proxy email address (Token@host.tld) is automatically created and provided to WebApp. WebApp then wishes to notify Customer, so WebApp sends the email to Token@host.tld. Host processes the notification, blocking notification if Customer has disabled that Token, or stripping non-text content and wrapping the notification for delivery to the registered Customer email.

In addition, Host may also submit the notification content to the Push Notification system for eventual display on Customers Push Notification enabled devices.

Requirements

• Host service shall accept BrowserID assertions as valid credentials for Customers
• Host service shall provide an optional randomized 256bit token which can be used as an email address.
  • Token shall consist of valid RFC5322 token generated from randomized 256bit number.
  • Allowances for "picky" MTAs may be accommodated, and the 256bit number may be converted to base36.
• Host service shall accept random, valid email token identifiers for Customer. (These tokens may be generated from the Host service or provided by the BrowerID managing agent.)

BrowserID has had a long standing request for an email redirect service. The service would accept mail addressed with an email safe, significant token as the local component, and redirect email to the principle registered email address of the user. Put far more clearly:

• A User logs into Site with BrowserID as "Bob@example.com"
• BrowserID then identifies User to Site as "a0b2c3@browserid.org"
• Site, wishing to send notifications to User, may now email "a0b2c3@browserid.org", which will then forward the message to "Bob@example.com"
• BrowserID adds a header/footer to the outbound message
• User may disable or drop "a0b2c3" from receiving mail at some time in the future if Site is overly chatty or that email address has been compromised.

Applications

BiPostal

BrowserID has had a long standing request for an email redirect service. The service would accept mail addressed with an email safe, significant token as the local component, and redirect email to the principle registered email address of the user. Put far more clearly:

• A User logs into Site with BrowserID as "Bob@example.com"
• BrowserID then identifies User to Site as "a0b2c3@browserid.org"
• Site, wishing to send notifications to User, may now email "a0b2c3@browserid.org", which will then forward the message to "Bob@example.com"
• BrowserID adds a header/footer to the outbound message
• User may disable or drop "a0b2c3" from receiving mail at some time in the future if Site is overly chatty or that email address has been compromised.

In order to perform this, Bipostal uses two PostFix milter functions. One being a non-smtpdfilter (bipostal), the other being a TCP tables filter (bipostmap).

Bipostmap

Bipostmap is very straight forward. It uses the PostFix TCP tables protocol to do the alias lookup. It connects to a REDIS database, and looks for a matching key value for "s2u:{TOKEN}" where {TOKEN} is the local-part of the incoming email address.

Bipostal

Bipostal uses the Milter protocol to modify the accepted email message for outbound delivery.

BiPostal API

The BiPostal system uses REST-like API calls to perform most of the work. Some of the API entry points have legacy names and may change

GET /0.5/new_token

Returns a new, mail local-part safe hash based on a 256bit random number

Arguments: {}

Returns: JSON complient string containing the new token

POST /0.5/user_queue

Creates returns the user's queue, creating if necessary.

Arguments: 'Credentials'

   Credentials are determined by the backend-auth mechanism used.
   For basic Auth they consist of the username and password.
   For browserId they consist of the assertion in the 'password'
   field with no 'username' required.

   Resolved User_id may be stored in beaker as 'uid' to bypass 
   credential check.
 
Returns: {'queue_id': token,
          'host': Submission host name,
          'port': Server access port}

   'queue_id' is the user's queue token. This id should be valid across 
   log-in credentials (e.g. if a user has "bob@example.com" and 
   "bjones@example.com", this ID would be consistent.

   'host' is the host URL to use for queue submission.

   'port' is the host PORT to use for queue submission.

POST /0.5/new_subscription

Create a new subscription for the user. Note: if this is a re-subsciption, the previous subscription value is returned.

Arguments: Request containing:
   'credentials' (see user_queue)
   'token' SMTP local-part compliant token. Either created from /new_token
       or generated by another source.
   'origin' site+tld (to be used to qualify token.)

POST /0.5/remove_subscription

Deactivate a subscription

Arguments: Request containing:
   'credentials' (see user_queue)
   'token' Subscription token to deactivate

BiPostalDash

While the mail service is accessible via web API calls, it's a good idea to provide some form of web front end to allow users to manage their account. To that end, a minimal server has been constructed to provide that functionality.

The current server is built as an extension of the Mozilla Push platform. Effort will be taken to refactor that into a stand alone application.

TODO

Known Bugs

o Re-examine Redis indexes for simplicity.
o Port redis-file data changes to mongo/memory models
o Add unit tests for bipostal
o Switch Beaker.session uid to be user token (from redis)

Outstanding tasks

Global

• Add comments / code cleanup
• Install to public box
• load testing

BiPostmap

• Add database abstraction layer (allow alternate stores like notifications uses)

BiPostal

• Strip HTML from incoming mail message
  • use only text elements of mail
  • ? handle attachments
• finalize header/footer
• ? append customer info data
• use standardized config loader

BiPostalUI

• Extract uicontroller and make separate pylons app.
• use standard config loader
• Allow for mulitple mail addresses
  • provide filtering (token => email address?)
• Add local BrowserID RSA signature checks
  • pull BrowserID public key from server
  • ? use rfkelly's browserid plugin
• ? Add usertoken to credential checks