Functional requirement

Covered services:

• Git push
• SVN commit
• Artifact changes (creation & update)

General behaviours:

• User is requested to upload it's GPG/PGP key in the account preference (1 key per account) like SSH
• Encryption is selected project per project by project admin (there is a record in project history for the switch)
• If an email address is used by several use accounts, a generic email is sent "you got a notification but serveral accounts (user1, user2,...) matches. Please use different email address per account."
• If an email address has no GPG/PGP key associated, a generic mail is sent "you got a notification from <platform url>, please add a gpg/pgp key"
• Specificities about email headers, they cannot be encrypted and can leak informations:
  • The subject of all encrypted emails (git, svn, artifacts) is "You got an email from <platform>"
  • No extra headers are sent (X-Tuleap-Project, X-Git-...)

Technical proposal

This is a new plugin

Artifact, git and svn are using different techno:

• Trackers are written in PHP
• Git notif in shell
• SVN in perl

New REST end point

In order to homogenize this, there is a new REST end point that will allow to send messages:

Note: the encryption will hook to this REST endpoint to encrypt.

POST /api/vX/messages
{
  ?"from": "X" (default noreply@platform),
  "to_emails": [ "Y" ],
  ?"project_id": XYZ,
  "subject": "X",
  "text": "X",
  "html": "X",
  ?"headers": ["X"],
  ?"force_crypt": true/false,
  ?"reply_to": "X", (/!\ subtlety with from != reply_to)
}

This end point is guarded with authorization & dedicated user:

• new dedicated user (forge__sendmail)/key would be reserved to send mail action shared by codendiadm (svn) and gitolite (git)
• new forge permission (send email)

This end point will manage the sending of email as well as encryption if needed (depend on value project_id). For encryption, there is a pecl package (already availble as RPM in remi repo, maybe EPEL too).

The emails must be sent user by user (to ease encryption) instead to: ... with comma (or to + cc).

Usage of new API

SVN & git

Both SVN and git will be modified to use a new CLI tool (tuleap-gitolite-membership like) that wraps the REST calls (authorization, token cache, etc). Example:

send_messages.php --from=X --to=Y --text=Z ...

Please note that token will be stored in files in user home directory and must be readable only by the user (codendiadm and gitolite ATM).

Artifacts

Artifacts will also call the REST api (locally) instead of sending emails directly. This requires to implement a new Codendi_Mail_Interface in a class that will call the rest API instead of directly sending email.

If possible, the call should by async (encryption can be time consuming)

References

Examples of public api to send emails:

• https://documentation.mailgun.com/api-sending.html#retrieving-stored-messages
• http://dev.mailjet.com/guides/send-api-guide/