silverstripe / silverstripe-realme

src/Model/FederatedIdentity.php

<?php

namespace SilverStripe\RealMe\Model;

use DOMDocument;
use DOMXPath;

use SilverStripe\ORM\FieldType\DBField;
use SilverStripe\View\ViewableData;
use SilverStripe\ORM\FieldType\DBDatetime;

/**
 * Class RealMeFederatedIdentity
 *
 * Contains data to describe an identity, verified by RealMe. Provides simpler access to identity information, rather
 * than having to parse XML via {@link DOMDocument} or similar.
 *
 * All public methods return individual elements from the federated identity.
 *
 * Standard usage:
 * Injector::inst()->get('RealMeService')->enforceLogin(); // Enforce login and ensure auth data exists
 * $identity = Injector::inst()->get('RealMeService')->getAuthData()->getIdentity();
 *
 * Notes:
 * - We can't store the original DOMDocument as it's not possible to properly serialize and unserialize this such that
 *   it can be stored in session. Therefore, during object instantiation, we parse the XML, and store individual details
 *   directly against properties.
 *
 * - See this object's constructor for the XML / DOMDocument object expected to be passed during instantiation.
 */
class FederatedIdentity extends ViewableData
{
    const SOURCE_XML = 'urn:nzl:govt:ict:stds:authn:safeb64:attribute:igovt:IVS:Assertion:Identity';
    const SOURCE_JSON = 'urn:nzl:govt:ict:stds:authn:safeb64:attribute:igovt:IVS:Assertion:JSON:Identity';

    /**
     * @var string The FIT (Federated Identity Tag) for this identity. This is the unique string that identifies an
     * individual, and should generally be mapped one-to-one with a {@link Member} object
     */
    private $nameId;

    /**
     * @var string The given first name(s) of the federated identity returned by RealMe.
     */
    public $FirstName;

    /**
     * @var string The given middle name(s) of the federated identity returned by RealMe.
     */
    public $MiddleName;

    /**
     * @var string The given last name of the federated identity returned by RealMe.
     */
    public $LastName;

    /**
     * @var string The gender of the federated identity returned by RealMe. Will be one of 'M', 'F', possibly 'U' or 'O'
     * (messaging specs are unclear).
     */
    public $Gender;

    /**
     * @var DOMNodeList Undocumented in RealMe messaging spec, generally describes the quality of birth info based

The type SilverStripe\RealMe\Model\DOMNodeList was not found. Did you mean DOMNodeList? If so, make sure to prefix the type with \.

     * presumably on the source.
     */
    public $BirthInfoQuality;

    /**
     * @var string The birth year of the federated identity returned by RealMe, e.g. 1993, 1954, 2015.
     * Probably better to use {@link getDateOfBirth()} which will return an {@link SS_Datetime} object.
     */
    public $BirthYear;

    /**
     * @var string The birth month of the federated identity returned by RealMe, e.g. 05 (May).
     * Probably better to use {@link getDateOfBirth()} which will return an {@link SS_Datetime} object.
     */
    public $BirthMonth;

    /**
     * @var string The birth day of the federated identity returned by RealMe, e.g. 05 (5th day of the month).
     * Probably better to use {@link getDateOfBirth()} which will return an {@link SS_Datetime} object.
     */
    public $BirthDay;

    /**
     * @var string Undocumented in RealMe messaging spec, generally describes the quality of birthplace info based
     * presumably on the source.
     */
    public $BirthPlaceQuality;

    /**
     * @var string The country of birth for the given federated identity returned by RealMe.
     */
    public $BirthPlaceCountry;

    /**
     * @var string The birthplace 'locality' of the federated identity returned by RealMe, e.g. 'Wellington', 'Unknown'
     */
    public $BirthPlaceLocality;

    public function __construct($nameId)
    {
        parent::__construct();
        $this->nameId = $nameId;
    }

    /**
     * Constructor that sets the expected federated identity details based on a provided DOMDocument. The expected XML
     * structure for the DOMDocument is the following:
     *
     * <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     * <ns1:Party
     *  xmlns:ns1="urn:oasis:names:tc:ciq:xpil:3"
     *  xmlns:ns2="urn:oasis:names:tc:ciq:ct:3"
     *  xmlns:ns3="urn:oasis:names:tc:ciq:xnl:3"
     *  xmlns:ns4="http://www.w3.org/1999/xlink"
     *  xmlns:ns5="urn:oasis:names:tc:ciq:xal:3">
     *     <ns1:PartyName>
     *         <ns3:PersonName>
     *             <ns3:NameElement ns3:ElementType="FirstName">Edmund</ns3:NameElement>
     *             <ns3:NameElement ns3:ElementType="MiddleName">Percival</ns3:NameElement>
     *             <ns3:NameElement ns3:ElementType="LastName">Hillary</ns3:NameElement>
     *         </ns3:PersonName>
     *     </ns1:PartyName>
     *     <ns1:PersonInfo ns1:Gender="M"/>
     *     <ns1:BirthInfo ns2:DataQualityType="Valid">
     *         <ns1:BirthInfoElement ns1:Type="BirthYear">1919</ns1:BirthInfoElement>
     *         <ns1:BirthInfoElement ns1:Type="BirthMonth">07</ns1:BirthInfoElement>
     *         <ns1:BirthInfoElement ns1:Type="BirthDay">20</ns1:BirthInfoElement>
     *         <ns1:BirthPlaceDetails ns2:DataQualityType="Valid">
     *             <ns5:Country>
     *                 <ns5:NameElement ns5:NameType="Name">New Zealand</ns5:NameElement>
     *             </ns5:Country>
     *             <ns5:Locality>
     *                 <ns5:NameElement ns5:NameType="Name">Auckland</ns5:NameElement>
     *             </ns5:Locality>
     *         </ns1:BirthPlaceDetails>
     *     </ns1:BirthInfo>
     * </ns1:Party>
     *
     * @param DOMDocument $identity
     * @param string $nameId
     */
    public static function createFromXML(DOMDocument $identityDocument, $nameId)
    {
        $identity = new self($nameId);

        $xpath = new DOMXPath($identityDocument);
        $xpath->registerNamespace('p', 'urn:oasis:names:tc:ciq:xpil:3');
        $xpath->registerNamespace('dataQuality', 'urn:oasis:names:tc:ciq:ct:3');
        $xpath->registerNamespace('n', 'urn:oasis:names:tc:ciq:xnl:3');
        $xpath->registerNamespace('xlink', 'http://www.w3.org/1999/xlink');
        $xpath->registerNamespace('addr', 'urn:oasis:names:tc:ciq:xal:3');

        // Name elements
        $identity->FirstName = self::getNodeValue(
            $xpath,
            "/p:Party/p:PartyName/n:PersonName/n:NameElement[@n:ElementType='FirstName']"
        );
        $identity->MiddleName = self::getNodeValue(
            $xpath,
            "/p:Party/p:PartyName/n:PersonName/n:NameElement[@n:ElementType='MiddleName']"
        );
        $identity->LastName = self::getNodeValue(
            $xpath,
            "/p:Party/p:PartyName/n:PersonName/n:NameElement[@n:ElementType='LastName']"
        );

        // Gender
        $identity->Gender = self::getNamedItemNodeValue($xpath, '/p:Party/p:PersonInfo[@p:Gender]', 'Gender');

        // Birth info
        $identity->BirthInfoQuality = $xpath->query("/p:Party/p:BirthInfo[@dataQuality:DataQualityType]");

It seems like $xpath->query('/p:Party/p:BirthInfo[@dataQuality:DataQualityType]') of type DOMNodeList or false is incompatible with the declared type SilverStripe\RealMe\Model\DOMNodeList of property $BirthInfoQuality.

        // Birth date
        $identity->BirthYear = self::getNodeValue(
            $xpath,
            "/p:Party/p:BirthInfo/p:BirthInfoElement[@p:Type='BirthYear']"
        );
        $identity->BirthMonth = self::getNodeValue(
            $xpath,
            "/p:Party/p:BirthInfo/p:BirthInfoElement[@p:Type='BirthMonth']"
        );
        $identity->BirthDay = self::getNodeValue(
            $xpath,
            "/p:Party/p:BirthInfo/p:BirthInfoElement[@p:Type='BirthDay']"
        );

        // Birth place
        $identity->BirthPlaceQuality = self::getNamedItemNodeValue(
            $xpath,
            '/p:Party/p:BirthInfo/p:BirthPlaceDetails[@dataQuality:DataQualityType]',
            'DataQualityType'
        );
        $identity->BirthPlaceCountry = self::getNodeValue(
            $xpath,
            "/p:Party/p:BirthInfo/p:BirthPlaceDetails/addr:Country/addr:NameElement[@addr:NameType='Name']"
        );
        $identity->BirthPlaceLocality = self::getNodeValue(
            $xpath,
            "/p:Party/p:BirthInfo/p:BirthPlaceDetails/addr:Locality/addr:NameElement[@addr:NameType='Name']"
        );

        return $identity;
    }

    public function isValid()
    {
        return true;
    }

    public function getDateOfBirth()
    {
        if ($this->BirthYear && $this->BirthMonth && $this->BirthDay) {
            $value = sprintf('%d-%d-%d', $this->BirthYear, $this->BirthMonth, $this->BirthDay);
            $dateTime = DBDatetime::create()->setValue($value);
            return $dateTime;
        } else {
            return null;
        }
    }

    /**
     * @param DOMXPath $xpath The DOMXPath object to carry out the query on
     * @param string $query The XPath query to find the relevant node
     * @param string $namedAttr The named attribute to retrieve from the XPath query
     * @return string|null Either the value from the named item, or null if no item exists
     */
    private static function getNamedItemNodeValue(DOMXPath $xpath, $query, $namedAttr)
    {
        $query = $xpath->query($query);
        $value = null;

        if ($query->length > 0) {
            $item = $query->item(0);

            if ($item->hasAttributes()) {
                $value = $item->attributes->getNamedItem($namedAttr);

                if (strlen($value->nodeValue) > 0) {
                    $value = $value->nodeValue;
                }
            }
        }

        return $value;

The expression return $value also could return the type DOMNode which is incompatible with the documented return type null|string.

    }

    /**
     * @param DOMXPath $xpath The DOMXPath object to carry out the query on
     * @param string $query The XPath query to find the relevant node
     * @return string|null Either the first matching node's value (there should only ever be one), or null if none found
     */
    private static function getNodeValue(DOMXPath $xpath, $query)
    {
        $query = $xpath->query($query);
        return ($query->length > 0 ? $query->item(0)->nodeValue : null);
    }

    /**
     * create a FederatedIdentity from a JSON string.
     *
     * @param string $identityHashMap
     * @param string $nameId
     * @return void
     */
    public static function createFromJSON($identityHashMap, $nameId)
    {
        $identity = new self($nameId);

        $identityMap = json_decode($identityHashMap, true);

        // Name elements
        $identity->FirstName = $identityMap['name']['firstName'];
        $identity->MiddleName = $identityMap['name']['middleName'];
        $identity->LastName = $identityMap['name']['lastName'];

        // Gender
        $identity->Gender = $identityMap['gender']['genderValue'];

        // Birth info
        $identity->BirthInfoQuality = $identityMap['dateOfBirth']['dateOfBirthDisputed'] ?: 'Valid';

It seems like $identityMap['dateOfBirth']['dateOfBirthDisputed'] ?: 'Valid' can also be of type string. However, the property $BirthInfoQuality is declared as type SilverStripe\RealMe\Model\DOMNodeList. Maybe add an additional type check?

        // Birth date
        $identity->BirthYear = explode('-', $identityMap['dateOfBirth']['dateOfBirthValue'])[0];
        $identity->BirthMonth = explode('-', $identityMap['dateOfBirth']['dateOfBirthValue'])[1];
        $identity->BirthDay = explode('-', $identityMap['dateOfBirth']['dateOfBirthValue'])[2];

        // Birth place
        $identity->BirthPlaceQuality = $identityMap['placeOfBirth']['placeOfBirthDisputed']?: 'Valid';
        $identity->BirthPlaceCountry = $identityMap['placeOfBirth']['country'];
        $identity->BirthPlaceLocality = $identityMap['placeOfBirth']['locality'];

        return $identity;

The expression return $identity returns the type SilverStripe\RealMe\Model\FederatedIdentity which is incompatible with the documented return type void.

    }
}