XMPP-JID

Parse and Create XMPP JIDs

What is this?

The xmpp-jid module is for both parsing and creating XMPP addresses, which are called JIDs.

A JID often looks a lot like an email address with a user@host form, but there's more to it:

        full JID
/                       \
[local@]domain[/resource]
\            /
   bare JID

A JID can be composed of a local part, a domain part, and a resource part. The domain part is mandatory for all JIDs, and can even stand alone (e.g., as the address for a server).

The combination of a local (user) part and a domain is called a "bare JID", and it is used to identitfy a particular account at a server.

A JID that includes a resource is called a "full JID", and it is used to identify a particular client connection (i.e., a specific connection for the associated "bare JID" account).

Installing

$ npm install xmpp-jid

Building bundled/minified version (for AMD, etc)

$ make

The bundled and minified files will be in the generated build directory.

Usage

var jid = require('xmpp-jid');

var res = new jid.JID('[email protected]');
// or jid.create('[email protected]/res');
//
// res == {
//     local: 'user',
//     domain: 'example.com',
//     resource: 'res',
//     bare: '[email protected]',
//     full: '[email protected]/res',
//     unescapedLocal: 'user',
//     unescapedBare: '[email protected]',
//     unescapedFull: '[email protected]/res',
//     prepped: true
// }

StringPrep

Correctly working with JIDs can be slightly tricky thanks to Unicode, which requires us to use StringPrep to normalize the individual parts of a JID so that we can safely use them in comparisons. Unfortunately, we don't have access to StringPrep in browsers, so all JID objects are marked with a prepped attribute indicating if StringPrep has been applied.

Comparisons between JIDs should only be trusted if both JIDs have prepped set to true.

The provided equal function can be used to reliably check that two JIDs are equivalent, with an optional parameter to disable the prepped flag check.

jid.equal('[email protected]/res', '[email protected]/res');
// true, if StringPrep is available


jid.equal('[email protected]/res', '[email protected]/res', false);
// true

jid.equal('[email protected]/res1', '[email protected]/res2');
// false, full JIDs don't match

The same applies for the provided equalBare function, which checks that two JIDs have the same "bare JID" form (i.e., it ignores differences in resources).

jid.equal('[email protected]/resource1', '[email protected]/resource2');
// true, if StringPrep is available


jid.equal('[email protected]/resource1', '[email protected]/resource2', false);
// true

jid.equal('[email protected]/resource1', '[email protected]/resource2', false);
// false, bare JIDs don't match

Even in the browser, there are ways to ensure that StringPrep is applied by getting your XMPP server to do the prepping for you. This is already done for the standard stanza routing attributes ("to" and "from"), and other places where the server can reliably ensure that the JIDs are prepped (e.g., roster entries).

In other cases, you may need to use XEP-0328: JID Prep to explicity ask your server to prep a given JID.

JID Escaping

XEP-0106: JID Escaping allows you to create JIDs using characters typically prohibited in the local part: "' <:>&@

When creating a new JID by specifying the local part separately (e.g. new JID('localpart', 'domain')), the local part will be automatically escaped where necessary.

(Using new JID('local@domain') will not escape the local part, as that is assumed to already be the escaped form.)

These fields on the resulting JID object yield the human-presentable, unescaped forms:

• unescapedLocal
• unescapedBare
• unescapedFull

If you show the unescaped forms anywhere to a user, you should do so everywhere to be consistent and prevent potential security issues related to JID spoofing.

License

MIT

Created By

If you like this, follow @lancestout on twitter.