betterangels / buoy

:sos: A community-based crisis response system. Because friends don't let friends call the cops. :fire::police_car::fire:

Buoy: A community-based crisis response system

Buoy is a decentralized 9-1-1 alternative built for and by people who are not well served by existing emergency response services. Buoy makes it easy to tell your friends where you are and what you need. Buoy's goal is a world where anyone in distress always has the option to turn to people they trust for support, rather than being forced to rely on people they don't.

Buoy is not a traditional "app" that you can download in the app store, but rather a system for adding crisis response and emergency dispatch services to existing websites. With Buoy, community groups, activist organizations, and social support service providers can quickly connect people who need help with trusted friends, family members, advocates, and other allies who can help them. It is designed to be community owned and operated, so each instance of Buoy can be customized to the unique needs or the organization or community group that hosts it.

Whether you are a group of street medics coordinating with each other during an action, citizen journalists or copwatchers watching each other's backs, domestic violence survivor support advocates, or even single parents picking each others’ kids up from school, Buoy helps you get and give peer-based mutual aid to your friends and comrades.

• See the screenshots for an example walkthrough of how Buoy works.
• Find a Buoy-enabled web site.
• Learn more about Buoy.

Installing Buoy for your community

If you already have a WordPress website, Buoy can be installed automatically from the WordPress plugin directory by searching for "Buoy" in the "Add New Plugin" screen of your WordPres admin site and clicking the "Install now" button. (Learn more about installing WordPress plugins from WPBeginner.com.)

Contributing

Buoy is free software. It was developed and is maintained primarily by a nomadic hacker named maymay who has a lot of fucks to give about supporting survivors of any of capitalism's horrors, along with a growing group of volunteers who call themselves the Better Angels.

Even if you don't code, there's a lot you can do to help make Buoy better. Here are a few.

Donate

You can support development and maintenance of Buoy by donating to our crowdfunding campaign, or by directly supporting its primary developer, maymay. Click here to donate via PayPal, or visit Cyberbusking.org for maymay's personal donation portal.

Translate

If you speak multiple languages, you can help translate Buoy into more human languages. This helps make Buoy available to people all over the world in their native languages.

Learn more by reading our Translator instructions.

Document

If you use Buoy and are familiar with how it works, you can help others learn about the tool by writing about how you use it. We maintain a wiki that you can edit to add your own guides, walkthroughs, and suggestions.

You can also write articles on your website or blog. If you do, please connect with us over social media or email to let us know.

Code

The easiest way to get started contributing code is to use the Varying Vagrant Vagrants ("VVV") project to make a local WordPress development environment. Then fork the Buoy project on GitHub and git clone your fork into your VVV's wordpress-default/wp-content/plugins/ directory. See our wiki for a step-by-step guide to setting up a development environment.

Patches and pull requests are very welcome! More information at our Developer documentation.

buoy's Issues

Predict likely current location of alerter based on initial geolocation and last seen lat/lng position

A client side overlay on the map showing a polyline of possible likely trajectories/positions might be useful.

Rationale is "what happens if an alerter suddenly goes silent/had their phone shut off or battery died?"

Constant location pings drains mobile device battery too quickly; adjust resource utilization based on battery level

See Battery Status API.

Can Buoy users opt to store alert information and evidence in a secure space that may be accessed by them at a later date?

If a victim does not want to immediately share particular evidence with law enforcement, the court system, medical providers, advocates, or anyone else, but may want to do so in the future, is there a way they could opt to collect the information about their reports and any associated evidence on a secure space online until they are ready to share that information? In that sense, would it be possible to use Buoy as a time, location, audio, and video collector of incidents without your circle being notified if desired?

Feature Request: Provide set-up guidance to new users

As a new user of Buoy, I found being immediately dropped into the Wordpress profile screen a bit confusing -- particularly because the Admin Color Scheme and Show Toolbar options at the very top are not typical options I am used to seeing when installing a new app. (Is there any way to remove these and start the profile at the Name section?)

The first time a new user logs into Buoy, consider displaying the following text either in a pop-up or at the top of the profile page:

"Welcome to Buoy. The Buoy tool connects people in crisis with the people they trust. In order to be available to respond to others in times of need, you must tell Buoy how you can be reached in an emergency. By default, all users receive crisis alerts by e-mail. To also receive crisis alerts by SMS, please supply your phone number in the field below. To create your personal emergency response team, click the My Team button in the left sidebar."

Media uploaded and attached to an incident post is public, but should be visible only to responders

This is an Insecure Direct Object Reference vulnerability as described by OWASP.

Two separate problems here that need fixing:

1. The media file should not be directly accessible (i.e., can link directly to media file itself)
2. The "attachment post" that WordPress creates when a user uploads media through Buoy is public, but should be private. (Done in 2f5fd50.)

The second issue is a simpler fix in Buoy through standard WordPress. The first issue requires more work. At a minimum, we should have Buoy itself check to ensure that browseable directory listings are not accessible (i.e., that would be what OWASP calls a "security misconfiguration" vulnerability).

Two possible ways to really fix the first problem are:

• Never serve files directly, but instead check them against a script
• Place Buoy-uploaded media outside the Web root.

There are challenges associated with both approaches.

The first approach ("never serve files directly") could be accomplished with the following steps:

• Ensure that the Buoy client always uploads files that are identifiable via pattern matching later, for instance: "buoy-media-upload-post-{$post_id}-{$filename}"
• Force the server to check the request URI (e.g., place .htaccess files in all newly-created media upload directories by default, figure out something similar for nginx and other HTTP servers? Can this be done more reliably with WordPress's own rewrite rules, or does this system kick in too late to do us any good for direct file accesses?)
• If the file name matches a Buoy media file, redirect to WP and attach a hook that performs an access check

The second approach is simpler (just do the upload ourselves). The problem there is to make sure we do actually have a writable directory to use, and then to securely proxy requests for these files from incoming legitimate users at the expected URIs.

"Safety Information" modal should automatically disappear when a responder enters shared chat

The shared chat implementation currently uses a tlk.io embedded chat, which means we cannot detect events that occur inside the chat from the app shell (because that would be XSS). I've asked the developers of Tlkio to see if they implemented or are willing to implement window.postMessage() for cross-origin event handling.

This issue is blocked until they either implement this feature or we implement our own chat solution. (IIRC, @vangogh72 mentioned some level of interest in possibly doing that?)

Layer heatmaps/color coded areas on incident maps based on municipal "open data"

Could it be useful to ingest municipal data such as "crime" stats or something and overlay this info as an optional layer in incident map screens?

Total unique responders should be shown when selecting teams to send an alert to

When a user selects the teams they want to send an alert to from the "Choose teams" panel, they should see how many individual accounts their alert will be sent to given the teams they selected. This is not as simple as it sounds because one account could be associated with more than one team.

For instance, say Alice has two teams (Team 1 and Team 2). Confirmed on Team 1 are Bob, Charlie and Dylan. Confirmed on Team 2 are Bob and Emily. When Alice only selects "Team 1" in the "Choose teams" panel, the readout should inform her of the fact that three (3) people will receive alerts (because there are three confirmed members of Team 1). Likewise, when she selects only "Team 2," the readout should say that two (2) people will receive alerts (because there are two confirmed members of Team 2).

If Alice selects both Team 1 and Team 2, the readout should inform her that four (4) people will receive alerts, not five, because even though there are five total members, one of those members (Bob) is on both Team 1 and Team 2.

Admins should be able to define "team templates" that users can add to their teams in one click

To make it easier for new users who join Buoys run by organizations, an admin could define a "team template that includes a pre-set list of responders with a suggested team name. A user can then add this template to their own actual teams list in one click to immediately invite (or outright add?) the users on said team template to a new list of their own.

This would dramatically help speed up utility of Buoy by letting new users try out a team designed by the organization itself.

See also betterangels/better-angels#19.

Allow users to toggle Team Members between "real" and "fake"

Feature request: Implement a "real/fake" toggle for existing members of a user's Team. This allows the user more control over who receives alerts from them, and lets them update their alert preferences based on who they feel comfortable contacting without having to notify a given team member that their status has changed.

(Possibly worth discussing: Does it make sense to let the toggle only go one way -- i.e. from Real to Fake, but not from Fake to Real. Or is this babysitting the user too much?)

Could Buoy immediately activate separate hidden mini-video/audio recording devices?

When a Buoy alert is activated, could it automatically and wirelessly activate mini cameras that a "victim" has hidden in their home, in a vehicle, on their body, or in any other location where they feel they could be threatened?

Add unit test coverage for e-mails

Add unit tests to make sure emails have the correct content, are sent with the correct "from" address of the alerter, etc.

Users should be able to list skills they have so others can find and select them in public listings easier

Folksonomy-style skill tagging system would be useful as an additional enhancement built for #72.

User interface should mimic or at least feel like a fun RPG-style adventure party selection screen, as per suggested Build Your Team campaign idea:

Video idea: A user appears to be selecting members for their raiding party in an RPG, looking at a list of characters with associated stats and abilities, but they are actually selecting members for their Buoy team. There are some shots of other users receiving invitation alerts on their phone and accepting them, but it still appears that they may be accepting invitations to play a game. The reveal occurs when the original user is caught in a crisis situation and sends a Crisis Alert -- the user's team members suddenly appear in real life.

CC: @unquietpirate.

Is it possible to activate Buoy through swiping or multiple click motions on your home screen?

Rather than a bookmark icon, can we use touch points, finger prints, or swiping patterns to activate Buoy?

Consider notifying user when they accept a Join My Team invitation that is no longer active

I wanted to see what would happen if I invited another user to join My Team, but then rescinded that invitation before the invited user had responded to it. These are the steps I took:

On two different browsers, I logged in as rebecca (Firefox) and fox (Safari) respectively. Rebecca invited fox to join her team. I received an invitation e-mail, and pasted the URL into fox's browser. This took me to the "Confirm Team Membership" page where a pending invitation from rebecca was visible.

I then switched back to rebecca's browser, where fox was listed as a pending team member. I unchecked fox and hit Save Changes, removing fox "(pending)" from my team.

Finally, I returned to fox's browser, where the invitation was still visible (because I had not reloaded the page), accepted the invitation, and hit Save Changes. The page reloaded to the default "you have not been invited to join any teams" screen.

This may be confusing to users who either a) happen to have not reloaded their Team Membership page and, therefore, are still seeing invitations that have been revoked or, more likely, b) who follow a link in an e-mail referring to an invitation that has since been revoked, and are taken to a Team Membership page displaying no invitations.

If a user attempts to respond to an invitation that is no longer active, consider notifying them that "This invitation is no longer active"?

Consider bundling assets into the plugin itself rather than loading from CDNs

Doing this would theoretically improve the privacy of users by ensuring third-parties aren't used to load pages, and it would also mean we don't need to deal with subresource integrity issues.

On the other hand, it could be a lot of framework code and further burden/slow down smaller or less-optimized WordPress sites.

I'm not sure what the best trade-off here is. A discussion about the relevant issues is needed.

Detect lack of 2nd factor authentication and suggest it be added

When installing Buoy, an admin should be guided to implementing security best practices, especially because they may not be technicaly savvy themselves. The NNEDV App Safety Center recommends the use of 2FA mechanisms to protect online accounts for DV victims and survivors, so we should detect the presence or absence of such additional account security means and warn the admin user if they are missing.

Enable users to receive emergency alerts over any/all "contact detail" methods they define in their profile

For instance, if a user supplies an XMPP/Jabber ID, Buoy should be able to send them a Jabber message (i.e., an Instant Message) with the contents of the emergency alert.

Same should be possible for a Twitter account (via direct message), and so on.

Buoy messages being delivered to Spam

Buoy messages are being delivered to Gmail's spam folder(in my case); this includes the alert messages.
Instructions may need to be created to inform users about adding Buoy's links to personal email address books to enable successful inbox delivery.

Option for admins to define a new users initial team(s) setup

A Buoy admin should be able to define the initial team setup for newly registered/created users. This will reduce the end user effort without compromising their ultimate ability to control their own teams.

See also betterangels/better-angels#19.

Send alert as tweet if user has a Twitter account

When a user issues a new alert, that alert could be sent as a Tweet.

Only send an alert as a tweet if the user opts into this capability (and connects their Twitter account, of course), otherwise this could be seen as an obvious privacy issue caused by "misconfiguration." But the defaults should match the most private expectations.

The tweet MUST NOT contain any Buoy-specific information (like a "responder" URL), because the Tweet is a public message and people who are not responders may see it.

The tweet SHOULD contain the alert location and its message (if any).

In the activate alert screens, near the "Choose teams" panel, there should be an option to toggle tweeting this alert on or off. If this information is not received by the server or if the toggle is set to off, the alert MUST NOT post a tweet, too.

My rationale for this feature is that in many cases, an "emergency" is not specific to a group of trusted people. For instance, a house fire is an emergency but, in general, any capable bystander can help address this crisis. A user generally has the best idea of whether or not their "emergencies" are ones that they only want a trusted group of people to respond to, or if they just need to digitally shout "help" and get help from anyone as soon as possible. This may be especially useful for the "Safe call" feature, in which case this feature would function as a kind of "public" alert that something may have happened to the user.

See also: betterangels/better-angels#40, RFC 2119.

Buoy's built-in chat room messages should be end-to-end encrypted to current responders

Some experimental possible implementations could be:

• OpenPGP scheme with https://openpgpjs.org/
• OTR scheme (preferred if feasible) with https://github.com/arlolra/otr

See also draft spec on the wiki.

Uploaded media cannot be sent (is not visible) to responders in chat room

Any media uploaded only appears in the drop-down menu under its specified file category. There is no option available to send the media or post the media to be visible to team members in a chat room.
Once an uploaded file is selected, a new computer tab opens to display a larger view of the file but no further action is carried out after that.

Add metadata on user account for whether user has a legal requirement to call cops

Some users may be using Buoy in their professional role as a counselor, therapist, or other institutionally-backed service provider. These users have specific legal requirements that are often a risk to their clients, such as a legal obligation to call State actors (cops) who may be untrusted by the people contacting them for help. It is important for alerters to know whether anyone they choose to add to their response team has such a legal obligation so that they can be better informed about the risks they take when alerting these specific users of crisis situations.

See also #81.

Integration with GuardianProject's "Ripple" panic button trigger

The Guardian Project has a "panic button library" for Android apps that can be used to send a "panic trigger" to any apps that register themselves as a "panic responder." When Buoy obtains a native shell Android app, we should incorporate this functionality so that users can configure the native Buoy app to respond to this trigger.

More reliable SMS delivery mechanism than email-to-SMS gateway?

The email-to-SMS gateways of individual phone providers are not as reliable as we might wish they were. Are there better alternatives that meet our needs?

Some options to consider:

• https://cel.ly/solutions/activism
• https://www.twilio.com/sms
• https://www.mobilecommons.com/solution/nonprofits-causes/

Some of these are costly (i.e., will demand a sum of money). Any such path must be implemented as an optional enhancement and have an SMS/email gateway fallback as well.

Immediate transfer to a working admin site if the admin site connected to a Buoy signal is down.

Prompt user to confirm leaving a team before removing them from team.

A small suggestion on leaving team. Maybe there could be a alert message asking the user if you're sure if you want to leave the team. The user might click on that button by accident.

Viewing a video attached to an incident that doesn't have an in-browser player UI prevents user from returning to incident chat

We need to manually check the video media types to see if the wp_video_shortcode() can generate a player for us. If not, we need to create a player ourselves.

This is because iOS devices using Buoy as in webapp-capable mode will not be able to return back to the incident chat screen after viewing a video directly. (They need a video players UI embedded in the browser.) This requires the user to exit Buoy, then re-launch it, in order to return to their incident chat room.

Add basic server-side geolocation via some GeoIP database

Various WordPress plugins already exist for these purposes, such as https://wordpress.org/plugins/geoip-detect/

We should be able to detect the presence of these plugins and, if found, use their functionality to provide basic geo-IP location to supplement users who are browsing with JavaScript disabled.

Key places where this can be added is in the "review alert" (responder screen), where we can write a geolocated IP lat/long value into the Respond form so that we have an initial guess of that responder's location even when they respond to an alert with JavaScript disabled.

Can we add user-generated offline geolocation navigation?

Google offers offline mapping and tracking.

http://techcrunch.com/2015/11/10/offline-navigation-comes-to-google-maps/

Would it be possible to allow both service providers (legal aid, shelters, advocacy groups, etc) and end users to collectively add maps so users who lose internet connection or are without connection will also be able to use Buoy location tracker?

Provide visual feedback of media upload progress

Currently, uploading media to an incident chat happens in the background, with no indication of success, failure, or progress in the UI. There should be some visual feedback during this process so a user knows the upload is proceeding.

Add `apple-touch-startup-image` for iOS web app version

I've been having some trouble doing this even though it seems like it should be simple (the startup image is not showing up in my testing), so I'm putting this issue in as a note to myself to spend some time figuring out what I'm doing wrong later.

Teams should have associated icons (post thumbnails)

These icons should be deleted when the team itself is deleted.

Let admins customize map view by adding resources as markers to map

When a user activates an alert they are able to see their current location on a Google Map. It would benefit many classes of emergencies for the user to see markers on the map of helpful information (maybe depending on the type of alert?) such as the locations of nearby shelters, food pantries, hospitals, planned parenthood clinics, etc.

The admin of a site shouod be able to create a map of resources independent of Buoy (Google My Maps, for instance) that can then be overlaid on top of the map in alert (and responder) view.

Feature request: Allow users to store personal information that may be useful to responders

Some personal information stored in advance about a user might be valuable to responders in a crisis e.g. medications taken, severe allergies, "my brother has a key to my house -- you can contact him at XXX-XXXX", names/ages/location of children's school, pets, preferences about hospitalization, etc.

Is there a way information like this could be stored in a user's profile in a way that responders can easily access through the alert interface?

Highlight the presence of incident media if present in the incident chat screen

If there is incident media attached to an alert when a responder enters the Incident Chat screen, they should have some visual indication that this is the case. Perhaps a color (or numeric badge?) on the "Upload Media" button?

"beacon" feature where activating an alert also causes camera flash to flash like strobe and sounds to play loudly

Useful for street medic use case, probably not possible until native shell app is developed?

Users should be notified if they lose all their responders for any reason

There may be a number of circumstances in which a Buoy user might be left without any team members:

• The team members remove themselves from teams they have been added to.
• The site admin deletes the accounts of a given user's team members.
• The user themselves (accidentally?) removes all team members.

Since some of these may occur without any interaction of the user themselves, and may very well happen even if the user never returns to the site, they should be notified (via email?) that they have lost their potential responders and that the "Activate Alert" screen will not actually be sending alerts to anyone!

Can users allow those in their circle to hear/see real-time recordings collected by Buoy?

Is it possible to allow those who receive emergency alerts through Buoy to also observe any evidence collected by the app from the time of the alert to the current time? I would see the purpose as access to real-time observation of the situation, even from a distance. Listening to a conversation, sounds that indicate violence, a car door slamming, or other pieces of information could add to a responder's ability to help in as informed a capacity as possible.

Would it be possible for users to select only particular members of their group to be able to observe this information?

"Evidence capture" mode where activating an alert begins to stream audio/video capture from device's built-in microphone and camera if it has one

See also #45 as a complementary feature.

Change "real/fake" to something more explanatory: "active/inactive"?

For "dumbphone" users, bridge SMS interface to incident chat room

For an alerter: an ability to txt HELP or some other similar command to an SMS-capable phone number that Buoy can receive.

For a responder: the ability to respond RESPOND or some other similar command to an SMS-capable phone number that Buoy can receive.

When a responder responds via SMS, forward messages from the chat room to the responder's SMS number. Forward any further messages sent from the responder's dumbphone via SMS into the chat room for the other responders to read. The special command ALERT STOP or something can leave the chatroom.

Basically, a bridge between the smartphone-capable interface and an SMS-only interface should eventually be implemented to support anyone who does not have access to a smartphone.

enhancement: integrate with push to talk functionality

As part of native app

Extend login cookie for "Buoy-only" users to avoid login reprompt

For some use cases, there will be many technically unsophisticated users who have an account and only log in for using Buoy. These users are likely to be Subscribers who have a response team set. For these users, Buoy could continually extend the life of their WordPress login cookie so that they will not be reprompted to log in to the site after the default WordPress cookie expiration time of 2 weeks is over.

This would make the event that a casual user suddenly needs to use the panic screen as frictionless as is safe to make.

Define "on-call advocate" who (always?) receives an alert depending on on-call shift schedule

Some organizations may have specialized medical, legal aid, or survivor advocate positions that are always "on-call" given a particular schedule. There should be a way for admins to define who those users are, their roles, and their on-call schedules so that those support roles can be automatically added to the response Team for users who activate alerts.

On small screens, cannot scroll "Schedule an alert" dialog after receiving an error

Browser: Mozilla Firefox version 42 on Android

Steps to reproduce:

1. Navigate to "Schedule an alert" dialog
2. Verify that the dialog can be scrolled in the viewport
3. Enter an invalid date/time (or leave it blanl, as blank is invalid)
4. Press the "Schedule alert" button
5. Receive the error ("Buoy does not understand the time and date you entered)
6. Try to scroll the window, dialog does not move

Expected result:

• Receiving an error does not affect scrollability of the dialog.

Impact:

• On small enough screens, the inability to scroll coupled with the vertical height of the error message means the "Schedule alert" button is not accessible.

"Add a team member" should accept phone numbers?

Look up users' phone numbers if any already existed?

What are the concerns for phone number enumeration?

Show summary of other available Buoys (gathered by Lighthouse) somewhere in Buoy's own interface

This is a thought - Could we add an a landing page that, at some point after a Buoy alert has been triggered, those in crises are provided with a list of available resources provided by Lighthouses. Those who have triggered an alert could select particular types of resources from a list and receive the location and contact information of that Lighthouse. This would allow users to search with a resource filter. Is this already noted in an issue? Couldn't find one but not sure.

Complete scenario/use-case writeups for Buoy

See Buoy Use Cases.

Ping @unquietpirate @nitishnarula especially.