You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/proposals/4369-capability-error-code.md

4.2 KiB

MSC0000: M_CAPABILITY_NOT_ENABLED error code for when capability is not enabled on an API endpoint

The capabilities negotiation feature in the Client-Server API provides a mechanism for clients to discover whether specific capabilities are available to a user.

However, the endpoints that use capabilities do not currently specify what error response a client should expect if they try to use an API that does not have the capability enabled for the user.

I believe this is an omission in the current spec that should be addressed for existing capabilites and be checked for future MSCs that use capabilities.

For background: this MSC originates from a spec PR that has since been closed.

Proposal

Define a new other error code of M_CAPABILITY_NOT_ENABLED.

Define the following behaviour for existing API endpoints that use capabilities:

Capability Endpoint(s) Current spec Proposed behaviour
m.change_password POST /_matrix/client/v3/account/password Not defined Return 403 with M_CAPABILITY_NOT_ENABLED if m.change_password.enabled is false
m.profile_fields PUT /_matrix/client/v3/profile/{userId}/{keyName} DELETE /_matrix/client/v3/profile/{userId}/{keyName} 403 for PUT. Maybe 403 for DELETE. Error code not specified for either Return 403 with M_CAPABILITY_NOT_ENABLED if: m.profile_fields.enabled is false; or, m.profile_fields.disallowed contains {keyName};
m.set_displayname As per m.profile_fields As per m.profile_fields Return 403 with M_CAPABILITY_NOT_ENABLED if: m.profile_fields.enabled is false; or, m.profile_fields.disallowed contains {keyName}; or, m.set_displayname.enabled is false;
m.set_avatar_url As per m.profile_fields As per m.profile_fields Return 403 with M_CAPABILITY_NOT_ENABLED if: m.profile_fields.enabled is false; or, m.profile_fields.disallowed contains {keyName}; or, m.set_avatar_url.enabled is false;
m.3pid_changes POST /_matrix/client/v3/account/3pid POST /_matrix/client/v3/account/3pid/add POST /_matrix/client/v3/account/3pid/delete Not defined Return 400 with M_CAPABILITY_NOT_ENABLED if m.3pid_changes.enabled is false
m.get_login_token POST /_matrix/client/v1/login/get_token Maybe 400 with undefined error code if m.get_login_token.enabled is false 403 with M_CAPABILITY_NOT_ENABLED if m.get_login_token.enabled is false

Potential issues

TODO: Change in behaviour on m.get_login_token.

Alternatives

Base on existing implementations. This is what was originally in https://github.com/matrix-org/matrix-spec/pull/2212

Security considerations

None.

Unstable prefix

Whilst this proposal is under development the IO.ELEMENT.MSCXXXX_CAPABILITY_NOT_ENABLED value should be used instead of CAPABILITY_NOT_ENABLED.

Dependencies

None.