identity

class gratipay.models.participant.identity.Identity[source]

This mixin provides management of national identities for Participant objects.

A participant may have zero or more national identities on file with Gratipay, with at most one for any given country at any given time. When at least one of a participant’s national identities has been verified, then they may join one or more Teams.

Since national identity information is more sensitive than other information in our database, we encrypt it in the application layer before passing it to the database in store_identity_info(). We then limit access to the information to a single method, retrieve_identity_info().

has_verified_identity = False

True if the participant has at least one verified identity on file, False otherwise. This attribute is read-only. It is updated with set_identity_verification() and clear_identity().

store_identity_info(country_id, schema_name, info)[source]

Store the participant’s national identity information for a given country.

Parameters:
  • country_id (int) – an id from the countries table
  • schema_name (dict) – the name of the schema of the identity information
  • info (dict) – a dictionary of identity information
Returns:

the id of the identity info’s record in the participant_identities table

Raises:
  • ParticipantIdentitySchemaUnknown – if schema_name doesn’t name a known schema
  • ParticipantIdentityInfoInvalid – if the info dictionary does not conform to the schema named by schema_name

The info dictionary will be serialized to JSON and then encrypted with EncryptingPacker before being sent to the database. We anticipate multiple schemas evolving for this dictionary, with enforcement in the application layer (since the field is opaque in the database layer). For now there is only one available schema: nothing-enforced.

New participant identity information for a given country always starts out unverified.

retrieve_identity_info(country_id)[source]

Return the participant’s national identity information for a given country.

Parameters:country_id (int) – an id from the countries table
Returns:a dictionary of identity information, or None
list_identity_metadata(is_verified=None)[source]

Return a list of identity metadata records, sorted by country name.

Parameters:is_verified (bool) – filter records by whether or not the information is verified; None returns both

Identity metadata records have the following attributes:

Variables:
  • id (int) – the record’s primary key in the participant_identities table
  • country (Country) – the country this identity applies to
  • schema_name (unicode) – the name of the schema that the data itself conforms to
  • is_verified (bool) – whether or not the information has been verified

The national identity information itself is not included, only metadata. Use retrieve_identity_info() to get the actual data.

set_identity_verification(country_id, is_verified)[source]

Set the verification status of the participant’s national identity for a given country.

Parameters:
  • country_id (int) – an id from the countries table
  • is_verified (bool) – whether the information has been verified or not

This is a no-op if the participant has no identity on file for the given country_id.

clear_identity(country_id)[source]

Clear the participant’s national identity record for a given country.

Parameters:country_id (int) – an id from the countries table
gratipay.models.participant.identity.rekey(db, packer)[source]

Rekey the encrypted participant identity information in our database.

Parameters:

This function features prominently in our procedure for rekeying our encrypted data, as documented in the “Keep Secrets” howto. It operates by loading records from participant_identities that haven’t been updated in the present month, in batches of 100. It updates a timestamp atomically with each rekeyed info, so it can be safely rerun in the face of network failure, etc.