Merge ~pelpsi/launchpad:social-account-interface-and-implementation into launchpad:master

[Simone Pelosi]

SocialAccount interface and implementation

SocialAccount interface to reflect DB table SocialAccount:
each row of this new table is storing SocialAccount infomation
associated to one person. One person could have more than one
SocialAccount. This change is required since we are implementing
Matrix.

Reference: https://code.launchpad.net/~ines-almeida/launchpad/+git/launchpad/+merge/457221

[Ines Almeida (ines-almeida)]

From my initial look it looks generally good to me, just a few comments.
Also, as you had already mentioned, we will need to add more tests :)

Will get back to it and do a more in depth review in 2024 after the break!

[Ines Almeida (ines-almeida)]

Also to note, that this shouldn't be merged before the DB changes get merged and deployed. Will mark it as needs fixing to ensure we don't merge it too soon

review: Needs Fixing

[Ines Almeida (ines-almeida)]

We need to find a way to define how the JSON for a platform should look like (since some platforms will require only a nickname, and others will require nick + network, and eventually we might have even more complex schemas).

I'm wondering where we should add that, but I feel like it should perhaps be somewhere in the `PlatformType` class

[Ines Almeida (ines-almeida)]

LGTM!
Just a few comments regarding testing (won't approve until DB change is deployed)

[Guruprasad (lgp171188)]

review: Needs Fixing

[Guruprasad (lgp171188)]

Can you rename all occurrences of "social media platform" to "social platform" to be consistent?

review: Needs Fixing

[Ines Almeida (ines-almeida)]

Looking good, just a few minor comments

I'd like to have a good way to define stuff per platform (required identity fields, etc etc). But I think I'd rather move forward with what we currently have and generalize afterwards

review: Approve

[Simone Pelosi (pelpsi)]

I'm squashing commits into one.

[Guruprasad (lgp171188)]

> We need to find a way to define how the JSON for a platform should look like
> (since some platforms will require only a nickname, and others will require
> nick + network, and eventually we might have even more complex schemas).
>
> I'm wondering where we should add that, but I feel like it should perhaps be
> somewhere in the `PlatformType` class

I am not a fan of using the IRC-specific (or specific to few platforms) naming conventions for other services like Matrix. Matrix user IDs (MXID) use the format '@<email address hidden>' (see https://matrix.org/docs/older/faq/). So I would prefer using similar naming here - username and homeserver. It is better to store those separately instead of as an MXID because it will be easier to query accounts on a specific homeserver.

[Guruprasad (lgp171188)]

LGTM 👍

Please address the comments before merging.

review: Approve

[Ines Almeida (ines-almeida)]

Looking good, just a small remark on the validation!

review: Approve

[Ines Almeida (ines-almeida)]

Missing the "/" in the new username validation, otherwise all good!

review: Approve

diff --git a/lib/lp/registry/browser/configure.zcml b/lib/lp/registry/browser/configure.zcml
index 6fd29fb..046db06 100644
--- a/lib/lp/registry/browser/configure.zcml
+++ b/lib/lp/registry/browser/configure.zcml
@@ -665,6 +665,12 @@
         rootsite="api"
         />
     <lp:url
+        for="lp.registry.interfaces.socialaccount.ISocialAccount"
+        path_expression="string:+socialaccount/${id}"
+        attribute_to_parent="person"
+        rootsite="api"
+        />
+    <lp:url
         for="lp.registry.interfaces.pillar.IPillarNameSet"
         path_expression="string:pillars"
         parent_utility="lp.services.webapp.interfaces.ILaunchpadRoot"
diff --git a/lib/lp/registry/browser/person.py b/lib/lp/registry/browser/person.py
index a741540..8f044fd 100644
--- a/lib/lp/registry/browser/person.py
+++ b/lib/lp/registry/browser/person.py
@@ -152,6 +152,7 @@ from lp.registry.interfaces.persontransferjob import (
 from lp.registry.interfaces.pillar import IPillarNameSet
 from lp.registry.interfaces.poll import IPollSubset
 from lp.registry.interfaces.product import InvalidProductName, IProduct
+from lp.registry.interfaces.socialaccount import ISocialAccountSet
 from lp.registry.interfaces.ssh import ISSHKeySet, SSHKeyAdditionError
 from lp.registry.interfaces.teammembership import (
     ITeamMembershipSet,
@@ -555,6 +556,14 @@ class PersonNavigation(BranchTraversalMixin, Navigation):
             return None
         return irc_nick
 
+    @stepthrough("+socialaccount")
+    def traverse_socialaccount(self, id):
+        """Traverse to this person's SocialAccount on the webservice layer."""
+        social_account = getUtility(ISocialAccountSet).get(id)
+        if social_account is None or social_account.person != self.context:
+            return None
+        return social_account
+
     @stepthrough("+oci-registry-credential")
     def traverse_oci_registry_credential(self, id):
         """Traverse to this person's OCI registry credentials."""
diff --git a/lib/lp/registry/configure.zcml b/lib/lp/registry/configure.zcml
index 3cf36a8..041e557 100644
--- a/lib/lp/registry/configure.zcml
+++ b/lib/lp/registry/configure.zcml
@@ -650,6 +650,33 @@
             interface="lp.registry.interfaces.jabber.IJabberIDSet"/>
     </lp:securedutility>
     <class
+        class="lp.registry.model.person.SocialAccount">
+        <allow
+            interface="lp.registry.interfaces.role.IHasOwner"/>
+        <allow
+            attributes="
+                id
+                person
+                platform
+                identity"/>
+        <require
+            permission="launchpad.Edit"
+            set_schema="lp.registry.interfaces.socialaccount.ISocialAccount"
+            attributes="
+                destroySelf"/>
+    </class>
+    <class
+        class="lp.registry.model.person.SocialAccountSet">
+        <allow
+            interface="lp.registry.interfaces.socialaccount.ISocialAccountSet"/>
+    </class>
+    <lp:securedutility
+        class="lp.registry.model.person.SocialAccountSet"
+        provides="lp.registry.interfaces.socialaccount.ISocialAccountSet">
+        <allow
+            interface="lp.registry.interfaces.socialaccount.ISocialAccountSet"/>
+    </lp:securedutility>
+    <class
         class="lp.registry.model.pillar.PillarName">
         <allow
             interface="lp.registry.interfaces.pillar.IPillarName"/>
diff --git a/lib/lp/registry/interfaces/person.py b/lib/lp/registry/interfaces/person.py
index 3aeae4c..a3cb45b 100644
--- a/lib/lp/registry/interfaces/person.py
+++ b/lib/lp/registry/interfaces/person.py
@@ -121,6 +121,10 @@ from lp.registry.interfaces.location import (
 from lp.registry.interfaces.mailinglistsubscription import (
     MailingListAutoSubscribePolicy,
 )
+from lp.registry.interfaces.socialaccount import (
+    ISocialAccount,
+    SocialPlatformType,
+)
 from lp.registry.interfaces.ssh import ISSHKey
 from lp.registry.interfaces.teammembership import (
     ITeamMembership,
@@ -1030,6 +1034,27 @@ class IPersonViewRestricted(
         ),
         exported_as="jabber_ids",
     )
+    social_accounts = exported(
+        CollectionField(
+            title=_("List of Social Accounts of this Person."),
+            readonly=True,
+            required=False,
+            value_type=Reference(schema=ISocialAccount),
+        )
+    )
+
+    @operation_parameters(
+        platform=Choice(
+            title=_("Social Platform Type"),
+            required=True,
+            vocabulary=SocialPlatformType,
+        )
+    )
+    @export_read_operation()
+    @operation_for_version("beta")
+    def getSocialAccountsByPlatform(platform):
+        """Return Social Accounts associated to the user."""
+
     team_memberships = exported(
         CollectionField(
             title=_(
@@ -3241,3 +3266,4 @@ patch_reference_property(IIrcID, "person", IPerson)
 patch_reference_property(IJabberID, "person", IPerson)
 patch_reference_property(IWikiName, "person", IPerson)
 patch_reference_property(IEmailAddress, "person", IPerson)
+patch_reference_property(ISocialAccount, "person", IPerson)
diff --git a/lib/lp/registry/interfaces/socialaccount.py b/lib/lp/registry/interfaces/socialaccount.py
new file mode 100644
index 0000000..1dcb7c8
--- /dev/null
+++ b/lib/lp/registry/interfaces/socialaccount.py
@@ -0,0 +1,160 @@
+# Copyright 2024 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""SocialAccount interfaces."""
+
+__all__ = [
+    "ISocialAccount",
+    "ISocialAccountSet",
+    "MatrixPlatform",
+    "SocialPlatformType",
+    "SocialAccountIdentityError",
+    "validate_social_account_identity",
+]
+
+import http.client
+import re
+
+from lazr.enum import DBEnumeratedType, DBItem
+from lazr.restful.declarations import (
+    error_status,
+    exported,
+    exported_as_webservice_entry,
+)
+from lazr.restful.fields import Reference
+from zope.interface import Interface
+from zope.schema import Choice, Dict, Int, TextLine
+
+from lp import _
+from lp.registry.interfaces.role import IHasOwner
+
+
+class SocialPlatformType(DBEnumeratedType):
+    """Social Platform Type
+
+    Social Account is associated with a SocialPlatformType.
+    """
+
+    MATRIX = DBItem(
+        1,
+        """
+        Matrix platform
+
+        The Social Account will hold Matrix account info.
+        """,
+    )
+
+
+# XXX pelpsi 2023-12-14 bug=760849: "beta" is a lie to get WADL generation
+# working.
+@exported_as_webservice_entry("social_account", as_of="beta")
+class ISocialAccount(IHasOwner):
+    """Social Account"""
+
+    id = Int(title=_("Database ID"), required=True, readonly=True)
+    # schema=Interface will be overridden in person.py because of circular
+    # dependencies.
+    person = exported(
+        Reference(
+            title=_("Owner"), required=True, schema=Interface, readonly=True
+        )
+    )
+
+    platform = exported(
+        Choice(
+            title=_("Social Platform Type"),
+            required=True,
+            vocabulary=SocialPlatformType,
+        )
+    )
+
+    identity = exported(
+        Dict(
+            title=_("Identity"),
+            key_type=TextLine(),
+            required=True,
+            readonly=False,
+            description=_(
+                "A dictionary with the identity attributes and values for the "
+                "social account. The format is specific for each platform. "
+                "Matrix account attributes: username, homeserver "
+            ),
+        )
+    )
+
+    def destroySelf():
+        """Delete this SocialAccount from the database."""
+
+
+class ISocialAccountSet(Interface):
+    """The set of SocialAccounts."""
+
+    def new(self, person, platform, identity):
+        """Create a new SocialAccount pointing to the given Person."""
+
+    def getByPerson(person):
+        """Return all SocialAccounts for the given person."""
+
+    def getByPersonAndSocialPlatform(person, social_platform):
+        """Return all SocialAccounts for the given person and platform."""
+
+    def get(id):
+        """Return the SocialAccount with the given id or None."""
+
+
+class SocialPlatform:
+    title = ""
+    identity_fields = []
+    platform_type = None
+
+    @classmethod
+    def validate_identity(cls, identity):
+        pass
+
+
+# XXX pelpsi: replace this with a pydantic validator
+class MatrixPlatform(SocialPlatform):
+    title = "Matrix"
+    identity_fields = ["username", "homeserver"]
+    platform_type = SocialPlatformType.MATRIX
+
+    @classmethod
+    def validate_identity(cls, identity):
+        if not all(
+            identity.get(required_field)
+            for required_field in cls.identity_fields
+        ):
+            raise SocialAccountIdentityError(
+                f"You must provide the following fields: "
+                f"{', '.join(cls.identity_fields)}."
+            )
+        if not isinstance(identity["username"], str):
+            raise SocialAccountIdentityError("Username must be a string.")
+        # Matrix username can contain a-z, 0-9, ., _, =, -, and /
+        # ref: https://spec.matrix.org/v1.1/appendices/#user-identifiers
+        username_patter = r"^[A-z0-9-=_./]+"
+        if not re.match(username_patter, identity["username"]):
+            raise SocialAccountIdentityError("Username must be valid.")
+        hs_pattern = r"^[A-z0-9][A-z0-9-]*(\.[A-z0-9]([A-z0-9-][A-z0-9])*)+$"
+        if not isinstance(identity["homeserver"], str):
+            raise SocialAccountIdentityError("Homeserver must be a string.")
+        if not re.match(hs_pattern, identity["homeserver"]):
+            raise SocialAccountIdentityError(
+                "Homeserver must be a valid domain."
+            )
+
+
+@error_status(http.client.BAD_REQUEST)
+class SocialAccountIdentityError(Exception):
+    """Raised when Social Account's identity is
+    invalid for a given Social Platform Type.
+    """
+
+
+def validate_social_account_identity(obj, attr, value):
+    social_account = obj
+
+    social_platform = social_account.getSocialPlatform()
+    social_platform.validate_identity(identity=value)
+
+    return value
diff --git a/lib/lp/registry/interfaces/webservice.py b/lib/lp/registry/interfaces/webservice.py
index 215c9ef..fc783eb 100644
--- a/lib/lp/registry/interfaces/webservice.py
+++ b/lib/lp/registry/interfaces/webservice.py
@@ -35,6 +35,7 @@ __all__ = [
     "IServiceFactory",
     "ISharingService",
     "ISSHKey",
+    "ISocialAccount",
     "ISourcePackage",
     "ISourcePackageName",
     "ITeam",
@@ -94,6 +95,7 @@ from lp.registry.interfaces.productseries import (
 )
 from lp.registry.interfaces.projectgroup import IProjectGroup, IProjectGroupSet
 from lp.registry.interfaces.sharingservice import ISharingService
+from lp.registry.interfaces.socialaccount import ISocialAccount
 from lp.registry.interfaces.sourcepackage import (
     ISourcePackage,
     ISourcePackageEdit,
diff --git a/lib/lp/registry/model/person.py b/lib/lp/registry/model/person.py
index 779616d..1a1a122 100644
--- a/lib/lp/registry/model/person.py
+++ b/lib/lp/registry/model/person.py
@@ -19,6 +19,8 @@ __all__ = [
     "PersonLanguage",
     "PersonSet",
     "PersonSettings",
+    "SocialAccount",
+    "SocialAccountSet",
     "SSHKey",
     "SSHKeySet",
     "TeamInvitationEvent",
@@ -40,6 +42,7 @@ import transaction
 from lazr.delegates import delegate_to
 from lazr.restful.utils import get_current_browser_request, smartquote
 from requests import PreparedRequest
+from storm.databases.postgres import JSON
 from storm.expr import (
     SQL,
     Alias,
@@ -161,6 +164,13 @@ from lp.registry.interfaces.persontransferjob import IPersonMergeJobSource
 from lp.registry.interfaces.product import IProduct, IProductSet
 from lp.registry.interfaces.projectgroup import IProjectGroup
 from lp.registry.interfaces.role import IPersonRoles
+from lp.registry.interfaces.socialaccount import (
+    ISocialAccount,
+    ISocialAccountSet,
+    MatrixPlatform,
+    SocialPlatformType,
+    validate_social_account_identity,
+)
 from lp.registry.interfaces.ssh import (
     SSH_TEXT_TO_KEY_TYPE,
     ISSHKey,
@@ -646,6 +656,7 @@ class Person(
     signedcocs = ReferenceSet("id", "SignedCodeOfConduct.owner_id")
     _ircnicknames = ReferenceSet("id", "IrcID.person_id")
     jabberids = ReferenceSet("id", "JabberID.person_id")
+    _social_accounts = ReferenceSet("id", "SocialAccount.person_id")
 
     visibility = DBEnum(
         enum=PersonVisibility,
@@ -688,6 +699,19 @@ class Person(
         return list(self._ircnicknames)
 
     @cachedproperty
+    def social_accounts(self):
+        return list(self._social_accounts)
+
+    # TODO: write test for this function once we have more
+    # than one Social Platform Type.
+    def getSocialAccountsByPlatform(self, platform):
+        return list(
+            getUtility(ISocialAccountSet).getByPersonAndSocialPlatform(
+                self, platform
+            )
+        )
+
+    @cachedproperty
     def languages(self):
         """See `IPerson`."""
         results = Store.of(self).find(
@@ -2779,6 +2803,7 @@ class Person(
             ("sharingjob", "grantee"),
             ("signedcodeofconduct", "owner"),
             ("snapbuild", "requester"),
+            ("socialaccount", "person"),
             ("specificationsubscription", "person"),
             ("sshkey", "person"),
             ("structuralsubscription", "subscriber"),
@@ -5321,6 +5346,67 @@ class WikiNameSet:
         return wiki_name
 
 
+@implementer(ISocialAccount)
+class SocialAccount(StormBase, HasOwnerMixin):
+    __storm_table__ = "SocialAccount"
+
+    id = Int(primary=True)
+    person_id = Int(name="person", allow_none=False)
+    person = Reference(person_id, "Person.id")
+    platform = DBEnum(
+        name="platform",
+        allow_none=False,
+        enum=SocialPlatformType,
+    )
+    identity = JSON(
+        name="identity",
+        allow_none=False,
+        validator=validate_social_account_identity,
+    )
+
+    def __init__(self, person, platform, identity):
+        super().__init__()
+        self.person = person
+        self.platform = platform
+        self.identity = identity
+
+    def getSocialPlatform(self):
+        if self.platform == SocialPlatformType.MATRIX:
+            return MatrixPlatform
+
+    def destroySelf(self):
+        IStore(self).remove(self)
+
+
+@implementer(ISocialAccountSet)
+class SocialAccountSet:
+    def get(self, id):
+        """See `ISocialAccountSet`."""
+        return IStore(SocialAccount).get(SocialAccount, int(id))
+
+    def getByPerson(self, person):
+        """See `ISocialAccountSet`."""
+        return (
+            IStore(SocialAccount)
+            .find(SocialAccount, person=person)
+            .group_by(SocialAccount.platform)
+        )
+
+    def getByPersonAndSocialPlatform(self, person, social_platform):
+        """See `ISocialAccountSet`."""
+        return IStore(SocialAccount).find(
+            SocialAccount, person=person, platform=social_platform
+        )
+
+    def new(self, person, platform, identity):
+        """See `ISocialAccountSet`."""
+        social_account = SocialAccount(
+            person=person, platform=platform, identity=identity
+        )
+        IStore(social_account).flush()
+        return social_account
+
+
 @implementer(IJabberID)
 class JabberID(StormBase, HasOwnerMixin):
     __storm_table__ = "JabberID"
diff --git a/lib/lp/registry/stories/webservice/xx-person.rst b/lib/lp/registry/stories/webservice/xx-person.rst
index 073c8a4..7e93f8b 100644
--- a/lib/lp/registry/stories/webservice/xx-person.rst
+++ b/lib/lp/registry/stories/webservice/xx-person.rst
@@ -53,6 +53,7 @@ for teams (as they're defined in the ITeam interface).
     recipes_collection_link: 'http://.../~salgado/recipes'
     resource_type_link: 'http://.../#person'
     self_link: 'http://.../~salgado'
+    social_accounts_collection_link: 'http://.../~salgado/social_accounts'
     sshkeys_collection_link: 'http://.../~salgado/sshkeys'
     sub_teams_collection_link: 'http://.../~salgado/sub_teams'
     super_teams_collection_link: 'http://.../~salgado/super_teams'
@@ -116,6 +117,7 @@ for teams (as they're defined in the ITeam interface).
     renewal_policy: 'invite them to apply for renewal'
     resource_type_link: 'http://.../#team'
     self_link: 'http://.../~ubuntu-team'
+    social_accounts_collection_link: 'http://.../~ubuntu-team/social_accounts'
     sshkeys_collection_link: 'http://.../~ubuntu-team/sshkeys'
     sub_teams_collection_link: 'http://.../~ubuntu-team/sub_teams'
     subscription_policy: 'Moderated Team'
@@ -635,6 +637,18 @@ to, obviously.
     HTTP/1.1 404 Not Found
     ...
 
+Social Accounts
+..........
+
+Social Accounts of a person are also linked.
+
+    >>> mark = webservice.get("/~mark").jsonBody()
+    >>> social_accounts_link = mark["social_accounts_collection_link"]
+    >>> print(social_accounts_link)
+    http://.../~mark/social_accounts
+    >>> print_self_link_of_entries(
+    ...     webservice.get(social_accounts_link).jsonBody()
+    ... )
 
 IRC nicknames
 .............
diff --git a/lib/lp/registry/tests/test_socialaccount.py b/lib/lp/registry/tests/test_socialaccount.py
new file mode 100644
index 0000000..6e45017
--- /dev/null
+++ b/lib/lp/registry/tests/test_socialaccount.py
@@ -0,0 +1,259 @@
+from zope.component import getUtility
+from zope.interface.verify import verifyObject
+
+from lp.registry.interfaces.role import IHasOwner
+from lp.registry.interfaces.socialaccount import (
+    ISocialAccount,
+    ISocialAccountSet,
+    SocialAccountIdentityError,
+    SocialPlatformType,
+)
+from lp.testing import TestCaseWithFactory, login_person
+from lp.testing.layers import DatabaseFunctionalLayer
+
+
+class TestSocialAccount(TestCaseWithFactory):
+    layer = DatabaseFunctionalLayer
+
+    def test_social_account(self):
+        # Social Account is created as expected and
+        # associated to the user.
+        user = self.factory.makePerson()
+        login_person(user)
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = "test-nickname"
+        social_account = getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+
+        self.assertTrue(verifyObject(IHasOwner, social_account))
+        self.assertTrue(verifyObject(ISocialAccount, social_account))
+
+    def test_matrix_account(self):
+        # Matrix Social Account is created as expected and
+        # associated to the user.
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = "test-nickname"
+        social_account = getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+
+        self.assertEqual(len(user.social_accounts), 1)
+        social_account = user.social_accounts[0]
+
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "abc.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+    def test_multilevel_domain_matrix_account(self):
+        # Homeserver with a multi-level domain is allowed
+        # Matrix username can contain a-z, 0-9, ., _, =, -, and /
+        # ref: https://spec.matrix.org/v1.1/appendices/#user-identifiers
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc-def.org-com"
+        attributes["username"] = "test-n/ic.kn=am_e"
+        social_account = getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+
+        self.assertEqual(len(user.social_accounts), 1)
+        social_account = user.social_accounts[0]
+
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(
+            social_account.identity["homeserver"], "abc-def.org-com"
+        )
+        self.assertEqual(
+            social_account.identity["username"], "test-n/ic.kn=am_e"
+        )
+
+    def test_malformed_identity_matrix_account(self):
+        # Matrix Identity must contain homeserver and username
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["name"] = "test-nickname"
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_malformed_username_matrix_account(self):
+        # Username can contain a-z, 0-9, ., _, =, -, and /
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = r"<b>test-nickname<\b>"
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_malformed_multilevel_domain_matrix_account(self):
+        # Homeserver cannot start with a special character
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "-def.org-com"
+        attributes["username"] = "test-nickname"
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+        attributes = {}
+        attributes["homeserver"] = "def.-org-com"
+        attributes["username"] = "test-nickname"
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_malformed_matrix_account_username(self):
+        # Username must be a string
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = 123123
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_malformed_matrix_account_homeserver(self):
+        # Homeserver must be a valid address
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc"
+        attributes["username"] = "test-nickname"
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_empty_fields_matrix_account(self):
+        # Identity field must be not empty
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = ""
+        attributes["username"] = "test-nickname"
+        utility = getUtility(ISocialAccountSet)
+
+        self.assertRaises(
+            SocialAccountIdentityError,
+            utility.new,
+            user,
+            SocialPlatformType.MATRIX,
+            attributes,
+        )
+
+    def test_multiple_social_accounts(self):
+        # Users can have multiple social accounts
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+        attributes = {}
+        attributes["homeserver"] = "def.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+
+        self.assertEqual(len(user.social_accounts), 2)
+        social_account = user.social_accounts[0]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "abc.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+        social_account = user.social_accounts[1]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "def.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+    def test_multiple_social_accounts_on_multiple_users(self):
+        # Users can have multiple social accounts
+        user = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "abc.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+        attributes = {}
+        attributes["homeserver"] = "def.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user, SocialPlatformType.MATRIX, attributes
+        )
+
+        user_two = self.factory.makePerson()
+        attributes = {}
+        attributes["homeserver"] = "ghi.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user_two, SocialPlatformType.MATRIX, attributes
+        )
+        attributes = {}
+        attributes["homeserver"] = "lmn.org"
+        attributes["username"] = "test-nickname"
+        getUtility(ISocialAccountSet).new(
+            user_two, SocialPlatformType.MATRIX, attributes
+        )
+
+        self.assertEqual(len(user.social_accounts), 2)
+        social_account = user.social_accounts[0]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "abc.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+        social_account = user.social_accounts[1]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "def.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+        self.assertEqual(len(user_two.social_accounts), 2)
+        social_account = user_two.social_accounts[0]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "ghi.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
+
+        social_account = user_two.social_accounts[1]
+        self.assertEqual(social_account.platform, SocialPlatformType.MATRIX)
+        self.assertEqual(social_account.identity["homeserver"], "lmn.org")
+        self.assertEqual(social_account.identity["username"], "test-nickname")
diff --git a/lib/lp/services/webservice/wadl-to-refhtml.xsl b/lib/lp/services/webservice/wadl-to-refhtml.xsl
index 0f6d973..4ddccb9 100644
--- a/lib/lp/services/webservice/wadl-to-refhtml.xsl
+++ b/lib/lp/services/webservice/wadl-to-refhtml.xsl
@@ -425,6 +425,12 @@
                 <xsl:text>/+jabberid/</xsl:text>
                 <var>&lt;id&gt;</var>
             </xsl:when>
+            <xsl:when test="@id = 'socialaccount_id'">
+                <xsl:text>/</xsl:text>
+                <var>&lt;person.name&gt;</var>
+                <xsl:text>/+socialaccount/</xsl:text>
+                <var>&lt;id&gt;</var>
+            </xsl:when>
             <xsl:when test="@id = 'irc_id'">
                 <xsl:text>/</xsl:text>
                 <var>&lt;person.name&gt;</var>