An open source password manager designed to work with Clef
Waltz recognizes sites by using the configuration files found in
site_configs
.
To make a site work with Waltz, add a json
file to the site_configs
directory. Please name the file with a key that identifies the domain you
are trying to add (google.com -> google.json
, facebook.com -> facebook.json
, news.ycombinator.com -> hackernews.json
).
Please also add a 150x150 png
with the site logo in static/img/site_images
using the same name as the config file.
For many sites, Waltz only needs a few required configuration options to work.
As a quick example, here is site_configs/localhost.json
:
{
"*://*.localhost/*": {
"name": "localhost",
"logout": {
"cookies": ["PHPSESSID"]
},
"login": {
"urls": ["http://localhost/"],
"formURL": "http://localhost/submitLogin",
"method": "POST",
"usernameField": "username",
"passwordField": "password",
"check": "#logged_in"
}
}
}
Let's step through each section.
-
*//*.localhost/*
object - the site's domain specified as a match pattern. Waltz will run on any page that matches this pattern. For example, Waltz will be run onhttps://localhost/hello
andhttp://sub.localhost/
.-
name
string — a human readable name. This is displayed in messages to the user. -
logout
object — configuration related to logging out.cookies
list (of strings) — a list of cookie names. Waltz will delete these cookies when a user logs out on their phone via Clef.
-
login
object — configuration related to logging in.urls
list (of strings) — a list of URLs that contain the site's login form. These are used to get hidden input fields, among other things.formURL
string — theaction
URL for the login form. The username and password are POSTed to this URL.method
string — themethod
of the login form, usually "POST".usernameField
string — thename
attribute of theinput
where you put your username.passwordField
string — thename
attribute of theinput
where you put your password.check
string — a jQuery selector for an element that only appears on a page you had to log in for. The best element to select for is the logout button or link.
-
In some cases, Waltz needs a little more information to work properly on more complicated sites. For instance, a site might have hidden inputs, two factor authentication, or might generate inputs with JavaScript.
Waltz has optional configs to handle some of these things as generally as possible. If we've left anything out, please open a pull request and add the config you need, or let us know in the issues.
Here is an example config that has only optional fields:
{
"*://*.example.com/*": {
"name": "Example.com",
"login": {
"hasHiddenInputs": true,
"submitButtonValue": "login",
"twoFactor": [
{
"url": "https://www.example.com/checkpoint/twoFactor",
"check": "input[name]='twoFactor_code'"
}
],
"exclude": {
"forcedRedirectURLs" : ["https://about.example.com/download"],
"nextURLs": ["https://example.com/login/captcha", "https://example.com/login/error"]
},
"formOnly": false
}
}
}
*://*.example.com/*
object-
login
objecthasHiddenInputs
boolean — specifytrue
if the login form has hidden inputs. IfhasHiddenInputs
istrue
, Waltz will request the login page in the background, (using the first URL inlogin.urls
) find all the hidden inputs, and submit them with the decrypted username and password.submitButton
string — A jQuery selector for the submit input in the login form. This is needed in rare cases to differentiate between the login form and other forms on the login page when the username and password fields have the same name (seesite_config/hackernews.json
).twoFactor
list (of strings)— a list of URLs that the user might be redirected to when they have two-factor authentication enabled. After logging a user in, Waltz automatically redirects the user to the page they were on when they clicked the Waltz icon. Explicitly specifying two-factor URLs ensures that Waltz will not forcefully redirect the user away from the two-factor page.exclude
object — these config options relate to whether Waltz will forcefully redirect the user back to a certain page or let the site handle the redirect itself.forcedRedirectURLs
list (of strings) — a list of URLs. If the user clicks the Waltz icon on any of these pages, Waltz will not redirect them back to this page, instead letting the page handle the redirect.nextURLs
list (of strings) — A list of URLs. If this user is redirected naturally to any of these URLs, Waltz will not attempt to redirect them back to the page on which they clicked the Waltz icon. It's useful to specify captcha URLs or error URLs here. Also, Waltz does not redirect the user away from login URLs if they are naturally redirected back to any of them after submitting their credentials. Waltz assumes that if a user is redirected back to a login page, that there was an error submitting the form.
formOnly
boolean — if the login form generates inputs using JavaScript, Waltz isn't able to submit the login form when not on the page, even if it is loaded in the background (seegoogle.json
. If this is the case, you can specify"formOnly": true
to only show Waltz if the user is on one of thelogin.urls
.
-