bellbox is a message routing and storage system

targets

• targets are either individual users or groups
• users may have multiple receivers (push, api calls)
• anyone may invite anyone to a group but only owners can forcibly remove people from the group

group

• collections of users
• valid targets

sender

• a sender is any system that can make api calls to notify a user
• senders must ask permission to send to a target

user

• api.example.com/user/new
• create a new user
• {"user": "myUsername", "password": "...."}
• returns an authorization header for all other api calls
• users may only be made administrators via database editing
• api.example.com/user/login
• same as new but for an existing user
• no email recovery feature

bell

• api.example.com/bell/new

• create a bell for a user

• body {"name": "bell name", "type": "BELLTYPE", "key": "BELLID"}

• reply {"id": "bellId", "bellDeleteSecret": "secret"}

• api.example.com/bell/map

• [{"id": "AUTOGENERATEDBELLID", "name": "bell name", "type": "BELLTYPE", "key": "only for web bell types"}] // maybe soon , "enabled": true}]

• get all the bells

• [maybe]

• api.example.com/bell/delete

• {"id": "bellId"} / {"id": "bellId", "bellDeleteSecret": "secret"}

• may be called with a bellId if using a user's authentication

• otherwise, a delete secret must be provided by the bell to remove itself (uninstallation, on/off toggling etc)

• api.example.com/bell/[on off]

• turn the bell on and off to enable/disable notifications being sent to it

bell key

• for an android app, this is your fcm token
  • a config.json file will need to be populated with your fcm server key
• for an ios app, this is your apns? token
  • a config.json file will need to be populated with paths to your certificates or whatever it is?
• for a web app, this is your callback url
  • nothing is required for this

bell types

• ANDROID
• IOS (unsupported right now)
• WEB

send

• api.example.com/send/TARGET/
• TARGET is an api target, defined below
• request {"title": "This is a test notification", "body": "This is a notification body", "priority": "normal"}
• must include Authorization header defined in bell ringer authentication

send priority

• urgent - this must be delivered, privacy must not be respected, this notification could be life changing or is deemed sufficently dangerous to violate basic security. don't use this unless you've got a dead mans switch about to throw or something
• high - delivery using high priority fcm/apns messages (message identification risk moderate until security padding increased/decreased based on priority)
• normal - deliver whenever
• silent - don't even show a notification

bellringer authentication

• api.example.com/auth/request
• request {"target": "user@system", "name": "Pizza Bell", "urgent": false}
• reply {"token": "bearer token"}
• Authorization: Bearer ...
• request credentials to access /send/ for a specific target
• must include if the bellringer plans to use urgent, allowing users to reject ringers with too-high priorities
• ringers without urgency will have their send priority capped to normal (until high is size safe)
• api.example.com/auth/disable
• disable the account for the given auth token. users will still see this as a valid sender

bellringer acceptance

• api.example.com/auth/map
• request {"type": "group"} // user is the default
• reply {"pending": [{"name": "Pizza Bell", "urgent": false, "clientId": "asdf"}], "accepted": []}
• get a map all of all granted or pending auth requests
• api.example.com/auth/accept
• api.example.com/auth/deny
• body {"clientId": ""}
• can be used at any time, but only by group admins

privacy

• to avoid size analysis, all payloads will be padded to the maximum message size
• this should be done by senders, but we cannot control their behaviour
• to avoid time analysis, regular delivery of keepalive packets with enough differing command data should exist