Description

With this change it will be possible to specify client-side TLS-certificate per origin.

It could be used in cases when a repository requires TLS-certificate to make an HTTPS request, ex. private package registry.
Technically without this PR it's possible to use client certificates for registries (by using repositories section of composer.json), but in that case path to certificate/key will we stored within the composer.lock, but when it is stored in VCS and each developer/CI has it's own certificate it stops working, for details see #12019.

Changes made by the way:

• #6688f21 add AuthHelper::addAuthenticationOptions to allow AuthHelper configure request options not only headers (to make this pr possible) and deprecate AuthHelper::addAuthenticationHeader
• #e8adca0 minor change to AuthHelper::addAuthenticationOptions, that helps simplify unit-test a bit - just noticed that during test implementation.

Examples (auth.json)

Minimal (certificate and key are in one file, the key is unencrypted):

{
    "client-certificate": {
        "exmaple.org": {
          "local_cert": "/path/to/cert.key.pem"
        }
    }
}

{
    "client-certificate": {
        "exmaple.org": {
          "local_cert": "/path/to/cert.pem",
          "local_pk": "/path/to/key.pem"
        }
    }
}

{
    "client-certificate": {
        "exmaple.org": {
          "local_cert": "/path/to/cert.pem",
          "local_pk": "/path/to/key.pem",
          "passphrase": "$uper$ecret"
        }
    }
}

Is it breaking change?

In general - no.
There may be some packages that rely on the deprecated AuthHelper::addAuthenticationHeader method, usage of which will trigger E_USER_DEPRECATED.

Is there other issues?

This PR doesn't bring issues by itself.

But there could be issues when auth.json has options multiple configurations for one domain (http-basic + client-cerntifcate), but the same issue will appear when there is configuration http-basic + bearer; in this case there will be a warning in log saying You should avoid overwriting already defined auth settings.

Other suggestions?

• current authentication array-shape (array{username: string|null, password: string|null}), forces all types of authentications to use this array in very odd way, ex. using password field as "authentication type", this PR use json_encode/json_decode to store configuration within username and using password to keep track authentication type;
• currently there is no way to combine multiple authentication (for one origin) without conflicts (ex, http-basic + bearer or http-basic + client-certificate), because of the way authentications are stored (array<origin_name, mixed>);
• it could be more efficient to add support for an option transport-options in auth.json (like is done in lock file), but in this case the file will be not about authentication, but "private transport configurations" (global or per-domain).