Module logins::login

Login Records

The core datatype managed by this component is a "login record", which contains the following fields:

• id: A unique string identifier for this record.

  Consumers may assume that id contains only "safe" ASCII characters but should otherwise treat this it as an opaque identifier. It should be left blank when adding a new record, in which case a new id will be automatically generated.

• hostname: The origin at which this login can be used, as a string.

  The login should only be used on sites that match this origin (for whatever definition of "matches" makes sense at the application level, e.g. eTLD+1 matching). This field is required, must be a valid origin in punycode format, and must not be set to the empty string.

  YES, THIS FIELD IS CONFUSINGLY NAMED. IT SHOULD BE A FULL ORIGIN, NOT A HOSTNAME. WE INTEND TO RENAME THIS TO origin IN A FUTURE RELEASE.

  Examples of valid hostname values include:

  • "https://site.com"
  • "http://site.com:1234"
  • "ftp://ftp.site.com"
  • "moz-proxy://127.0.0.1:8888"
  • "chrome://MyLegacyExtension"
  • "file://"
  • "https://[::1]"

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • truncating full URLs to just their origin component, if it is not an opaque origin
  • converting values with non-ascii characters into punycode

  XXX TODO:

  • return a "display" field (exact name TBD) in the serialized version, which will be the unicode version of punycode urls.
  • the great renaming

• password: The saved password, as a string.

  This field is required, and must not be set to the empty string. It must not contain null bytes, but can otherwise be an arbitrary unicode string.

• username: The username associated with this login, if any, as a string.

  This field is required, but may be set to the empty string if no username is associated with the login. It must not contain null bytes, but can otherwise be an arbitrary unicode string.

• httpRealm: The challenge string for HTTP Basic authentication, if any.

  If present, the login should only be used in response to a HTTP Basic Auth challenge that specifies a matching realm. For legacy reasons this string may not contain null bytes, carriage returns or newlines.

  If this field is set to the empty string, this indicates a wildcard match on realm.

  This field must not be present if formSubmitURL is set, since they indicate different types of login (HTTP-Auth based versus form-based). Exactly one of httpRealm and formSubmitURL must be present.

• formSubmitURL: The target origin of forms in which this login can be used, if any, as a string.

  If present, the login should only be used in forms whose target submission URL matches this origin. This field must be a valid origin or one of the following special cases:

  • An empty string, which is a wildcard match for any origin.
  • The single character ".", which is equivalent to the empty string
  • The string "javascript:", which matches any form with javascript target URL.

  YES, THIS FIELD IS CONFUSINGLY NAMED. IT SHOULD BE AN ORIGIN, NOT A FULL URL. WE INTEND TO RENAME THIS TO formActionOrigin IN A FUTURE RELEASE.

  This field must not be present if httpRealm is set, since they indicate different types of login (HTTP-Auth based versus form-based). Exactly one of httpRealm and formSubmitURL must be present.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • truncating full URLs to just their origin component
  • converting origins with non-ascii characters into punycode
  • replacing invalid values with null if a valid 'httpRealm' field is present

  XXX TODO:

  • return a "display" field (exact name TBD) in the serialized version, which will be the unicode version of punycode urls.
  • the great renaming (maybe we can do the punycode thing at the same time?)

• usernameField: The name of the form field into which the 'username' should be filled, if any.

  This value is stored if provided by the application, but does not imply any restrictions on how the login may be used in practice. For legacy reasons this string may not contain null bytes, carriage returns or newlines. This field must be empty unless formSubmitURL is set.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • setting to the empty string if 'formSubmitURL' is not present

• passwordField: The name of the form field into which the 'password' should be filled, if any.

  This value is stored if provided by the application, but does not imply any restrictions on how the login may be used in practice. For legacy reasons this string may not contain null bytes, carriage returns or newlines. This field must be empty unless formSubmitURL is set.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • setting to the empty string if 'formSubmitURL' is not present

• timesUsed: A lower bound on the number of times the password from this record has been used, as an integer.

  Applications should use the touch() method of the logins store to indicate when a password has been used, and should ensure that they only count uses of the actual password field (so for example, copying the password field to the clipboard should count as a "use", but copying just the username field should not).

  This number may not record uses that occurred on other devices, since some legacy sync clients do not record this information. It may be zero for records obtained via sync that have never been used locally.

  When merging duplicate records, the two usage counts are summed.

  This field is managed internally by the logins store by default and does not need to be set explicitly, although any application-provided value will be preserved when creating a new record.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • replacing missing or negative values with 0

  XXX TODO:

  • test that we prevent this counter from moving backwards.
  • test fixups of missing or negative values
  • test that we correctly merge dupes

• timeCreated: An upper bound on the time of creation of this login, in integer milliseconds from the unix epoch.

  This is an upper bound because some legacy sync clients do not record this information.

  Note that this field is typically a timestamp taken from the local machine clock, so it may be wildly inaccurate if the client does not have an accurate clock.

  This field is managed internally by the logins store by default and does not need to be set explicitly, although any application-provided value will be preserved when creating a new record.

  When merging duplicate records, the smallest non-zero value is taken.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • replacing missing or negative values with the current time

  XXX TODO:

  • test that we prevent this timestamp from moving backwards.
  • test fixups of missing or negative values
  • test that we correctly merge dupes

• timeLastUsed: A lower bound on the time of last use of this login, in integer milliseconds from the unix epoch.

  This is a lower bound because some legacy sync clients do not record this information; in that case newer clients set timeLastUsed when they use the record for the first time.

  Note that this field is typically a timestamp taken from the local machine clock, so it may be wildly inaccurate if the client does not have an accurate clock.

  This field is managed internally by the logins store by default and does not need to be set explicitly, although any application-provided value will be preserved when creating a new record.

  When merging duplicate records, the largest non-zero value is taken.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • removing negative values

  XXX TODO:

  • test that we prevent this timestamp from moving backwards.
  • test fixups of missing or negative values
  • test that we correctly merge dupes

• timePasswordChanged: A lower bound on the time that the password field was last changed, in integer milliseconds from the unix epoch.

  Changes to other fields (such as username) are not reflected in this timestamp. This is a lower bound because some legacy sync clients do not record this information; in that case newer clients set timePasswordChanged when they change the password field.

  Note that this field is typically a timestamp taken from the local machine clock, so it may be wildly inaccurate if the client does not have an accurate clock.

  This field is managed internally by the logins store by default and does not need to be set explicitly, although any application-provided value will be preserved when creating a new record.

  When merging duplicate records, the largest non-zero value is taken.

  If invalid data is received in this field (either from the application, or via sync) then the logins store will attempt to coerce it into valid data by:

  • removing negative values

  XXX TODO:

  • test that we prevent this timestamp from moving backwards.
  • test that we don't set this for changes to other fields.
  • test that we correctly merge dupes

In order to deal with data from legacy clients in a robust way, it is necessary to be able to build and manipulate Login structs that contain invalid data. The following methods can be used by callers to ensure that they're only working with valid records:

• Login::check_valid(): Checks valdity of a login record, returning () if it is valid or an error if it is not.

• Login::fixup(): Returns either the existing login if it is valid, a clone with invalid fields fixed up if it was safe to do so, or an error if the login is irreparably invalid.

Structs

LocalLogin
Login
LoginDelta
MirrorLogin
SyncLoginData

Enums

SyncStatus

Functions

deserialize_timestamp
string_or_default