.content
  = partial 'security_navigation'

  :textile
    h4. Securing your realtime applications

    Like any web-accessible service, Faye must be protected against malicious
    usage by attackers. Out of the box, it is a cross-domain-accessible server
    with no restrictions on subscribing and publishing, but its extension system
    allows you to easily impose restrictions appropriate to your application.

    Though written primarily for Faye, this guide contains advice that affects
    many realtime and socket-based applications. The core concerns with such
    applications are:

    * Can a client get access to data it should not have access to?
    * Can a client trust the origin of the messages it receives?

    The details of these questions will depend on your application, but the
    following is a set of general guidelines for avoiding broad classes of
    mistakes. It is not prescriptive, in that the solutions presented here are
    not how you _have to_ implement things. They simply try to illustrate
    patterns of security risks and possible solutions.

    As with all web applications, it is crucial to remember that any program
    with Internet access, including server-side scripts and in-browser
    JavaScript code on other domains, can send requests to your server. It is up
    to you to protect it and your users from harm.

    h4. What is Faye?

    Faye is an implementation of the "Bayeux":https://docs.cometd.org/current/reference/#_bayeux
    protocol. Clients send messages to each other via a central server, by
    sending JSON messages over various flavours of HTTP-based transport,
    including WebSocket, EventSource, XMLHttpRequest, CORS and JSON-P. Clients
    that run in the browser are not constrained by the same-origin policy.

    Messages are routed using subscriptions. When a client publishes a message,
    the server determines which clients are subscribed to the message's
    @channel@ and forwards the message to them verbatim. This means the
    _whole wire message is forwarded_, not just the @data@ field containing the
    application payload.

    A special set of channels whose names begin with @/meta/@ are used for
    operating the protocol itself, and messages sent to these channels are
    never forwarded to other clients.

    Messages pass through extensions on their way into and out of the clients
    and server. Data required by extensions is typically sent in the message's
    @ext@ field. Any changes made to a message by a server-side extension will
    be reflected in the messages forward to subscribed clients.

    Authorization credentials embedded in messages should be deleted from them
    by server-side extensions to prevent these credentials being forwarded to
    subscribed clients.

    h4. Transport layer security

    It should go without saying that if you want to keep the messages or any
    aspect of the HTTP transport layer secret from potential eavesdroppers, you
    should access the Faye server over a secure connection. You should use
    Node's @https@ module to create a server, or run Thin in SSL mode, or you
    can use an SSL terminator like STunnel in front of your Faye server.

    On the client side, you should make sure you use an @https:@ URL for the
    client to connect to.
