By submitting a pull request to this project, you agree to release your contribution under this project's license terms.
Before contributing, please review the Code of Conduct.
Contributing is easy! You can contribute either by raising compatibility issues with a website, researching and documenting what the right data for a quirk might be, and/or submitting a pull request to add a quirk. You can raise an issue at the repository's issues page. If you've done some investigation into a service's behavior, you can document it on an existing issue for that problem. If you'd like to submit a pull request, there are some additional special considerations for each type of quirk, detailed below.
When adding a data item to a top-level JSON object, please keep keys alphabetized. This assists with scanning the lists and with merging them. You may run the tools/validate-json-schemas.sh script to validate the JSON files before making a commit.
One more point to consider is to keep your pull requests small and limited in scope to a specific change. (For example, it's best to submit a "Password Rule" for a single website or group of related websites in one pull request and not conflate unrelated changes that can prevent other from being merged.)
Contributing a password rule is appropriate if a service doesn't accept a password generated by your password manager with its default settings or with a reasonable configuration. Contributing a rule involves writing a rule, testing it, documenting your investigation, and submitting a pull request.
To create a password rule, you'll want to gather as much information as you can about what the website considers to be an acceptable password. You can learn this by reading any pre-stated requirements or error messages you see while experimenting with the website. Sometimes, the rules might be human-readable, but not machine-readable. Other times, websites don't do a great job of saying what their rules are, or their stated rules are inaccurate, and you have to determine their actual rules experimentally.
Once you understand the website's requirements, like minimum length, maximum length, sets of required characters, and allowed characters, you're ready to write a rule. For example, a password rule that requires at least one uppercase character and one digit will require two "required: tags, e.g. required: upper; required: digit. Including both rules in one required: tag, e.g. required: upper, digit, will mean a password rule that requires either one uppercase character or one digit. This is unlike using the allowed: tag with a more lax password rule, where specifying allowed: upper, digit is equivalent to specifying allowed: upper; allowed: digit.
A detailed article on the syntax of the password rules can be found in the Customizing Password AutoFill Rules Apple Developer Document. Also, the Password Rules Validation Tool is a great tool for writing and validating password rules.
The Password Rules Validation Tool will output example passwords generated with the current rule, as well as allow you to download large sets of example passwords. You can copy and paste or manually type these passwords into the website to see if your rule creates compatible passwords. You should try to test a few different generated passwords to better ensure that you got it right.
Once you've tested passwords generated by your rule, you'll edit quirks/password-rules.json and add a new website key mapping to a JSON object of information. The rule you'll want to copy out of the Password Rules Validation Tools is the "Rules formatted for UIKit", because it's a pure Rule without any HTML markup.
When you submit a pull request to add or update a Password Rule, you should include as much information about the website’s requirements as you were able to gather. Text printed on the website, or error messages, are great. If the rules were determined experimentally, information about what you tried is helpful, too. Adding screenshots of error messages can be useful.
Each entry in quirks/shared-credentials.json and quirks/shared-credentials-historical.json is an object with the following valid sets of keys:
from,to, andfromDomainsAreObsoleted(fromDomainsAreObsoletedis optional)shared
from is an array of domains whose credentials should be shared one-way. This array cannot be empty.
to is an array of target domains that any credentials associated with the from domains should be allowed to match. This array cannot be empty.
fromDomainsAreObsoleted is a boolean that indicates whether or not the from domains in an entry have been obsoleted by the to domains (meaning logins are no longer served on the from domains). In the case of a redirect (such as discordapp.com -> discord.com), this would be true. Omission of the property means that it is false.
shared is an array of domains whose credentials are all shared. This array cannot be empty.
When contributing or amending a set of websites sharing a credential backend, you should state why you believe the relevant domains do or do not share a credential backend, with evidence to support your claim. This may involve WHOIS information or content served from the domains themselves.
Use the website in question until you find the standalone page for updating the user's password, or a high-level "Account Information" or "Security" page. The closer the URL takes the user to be able to change their password, the better. Before adding a URL, ensure that it works properly both when the user is logged in and when they are not. URLs added to quirks/change-password-URLs.json should have a scheme of https unless the website does not allow changing the password on an https page.
On macOS, for app bundle Example.app, you can find the App ID by dumping its entitlements with codesign -d --entitlements - --xml path/to/Example.app. Its App ID is the value in the XML for key com.apple.application-identifier. For macOS apps in particular, if there is no App ID present, the effective App ID is the app's Bundle Identifier (CFBundleIdentifier in the app's Info.plist).
When contributing or amending a set of websites for an App ID, you should state why you believe the domains do share a credential backend with the app, with evidence to support your claim.
When contributing or amending a set of websites that require that the user append a generated code to their password when signing in, you should state why you believe the relevant domains require such. This may involve citing a URL to the relevant support page for the website.
When contributing or amending the list of websites that when embedded as a third party, are known to ask for credentials for other services, you should provide evidence that the given website or websites behaves this way. This may involve a screenshot or steps to navigate a website to observe a subframe behaving this way.
If you have a new type of quirk or another resource, that you feel that other password managers could use to improve users' experiences and make password management more attractive for people who aren't using a password manager, please reach out to this project's maintainers at Apple so we can discuss the details.
If you are a representative from a website on the list, and you’ve incorporated the rule into your website or make it unnecessary, you can request a rule for your website to be removed. You can do this by filing an issue with the repository's issue tracker, or by submitting a pull request with a change. You may be asked to prove your affiliation with the service in question.