fxs – cross domain policy file server

A nodejs cross domain policy file server for Adobe Flash clients.

The server responds to cross domain policy file requests such as <policy-file-request/> with the cross domain policy file specified in the configuration.

The cross domain file is loaded when the server starts and monitored for changes; if it changes it is reloaded into memory.

See the cross domain policy file specification for more information.

When the server receives anything other than a <policy-file-request/> it behaves as an echo server.

Installation

Installation is done using npm:

npm install fxs

Configuration

Configuring the server options is achieved with a json configuration file, if no custom configuration file is specified when starting the server the default configuration file will be used.

{
    "port":     843,
    "host":     "127.0.0.1",
    "euid":     501,
    "watch":    true,
    "monitor": {
        "persistent": true,
        "interval": 0
    }
}

The host and port parameters are self-explanatory. The policy parameter is the file system path to the cross domain xml document that the server will send back to clients, if the policy parameter is omitted then the default cross domain policy file will be used.

In order to allow Flash clients to connect to ports below 1024 (a typical use case is raw socket access to a web server running on port 80) the server must be running on a port lower than 1024 which in turn entails starting the server as the root user.

Running processes as root is not a good idea so you must configure an euid parameter when running the server as root. If you do not configure euid and attempt to run as root you will see this error message:

fxs: running as root but no effective uid configured

To specify a username use a string value otherwise specify an integer of the uid for the user.

Once the server has bound to the privileged port the effective uid of the process is set using process.setuid( this.options.euid ).

watch

By default the cross domain policy file is watched for changes, if you know it won’t change or are prepared to restart the server when changing the cross domain policy file you should switch off the logic to watch the policy file:

{
    "watch": false
}

monitor

The monitor configuration specifies the options for the fs.watchFile() call, this can be used to alter the speed at which the policy file is polled:

{
    "monitor": {
        "persistent": true,
        "interval": 100
    }
}

The interval is the number of milliseconds to poll the file.

Server

To run the server from your program using the default configuration file (and default cross domain policy file):

var fxs = require( "fxs" );
fxs.start();

To run the server from your program using a custom configuration file:

var fxs = require( "fxs" );
fxs.start( "/fxs/conf/conf.json" );

Server Events

• error – Emitted when the server encounters an error.
• connected – Emitted when the server has successfully bound and is listening on the specified host and port.
• reload – Emitted when the server has successfully reloaded the cross domain policy file.
• closed – Emitted when the server has been closed.

Client

To send a policy file request to the server without using a Flash client you can do:

var fxs = require( "fxs" );
fxs.ping();

Or if you have changed the server port and host:

var fxs = require( "fxs" );
fxs.ping( 10000, "hostname" );

To listen for the cross domain policy response when sending a request use the policy event:

var client = fxs.ping();
client.on( "policy", function( contents )
{
    //do something
} );

When sending anything other than a policy file request, you can listen for the echo event:

var message = "hello world"
var client = fxs.client( port, host );
client.on( "echo", function( contents )
{
    //do something with echo response
} );
client.send( message );

Client Events

• error – Emitted when the client encounters an error.
• policy – Emitted when the client receives a cross domain policy file.
• echo – Emitted when the client receives an echo response.

Running the unit tests

Install nodeunit:

npm install nodeunit

Then execute (from the top-level directory of the source tree):

nodeunit test

To run all the tests in the test directory.

Building the Flash client test harness

Building the Flash client is done using maven and flexmojos, once you have maven (>= 3) installed you can run:

mvn clean install

Start the server running on the default 843 port:

sudo node server.js

And then open the index.html file within the target directory to view the Flash client test harness.

Roadmap

0.2.0

1. Improved example Flash client with configurable fields for host and port and ability to test connecting to mock http server on a port specifically allowed by the cross domain policy file.
2. Add command line binary programs.

0.1.0

1. Add proper error handling for the various socket, file io and configuration error cases.
2. Add support for executing as root and switching effective uid.
3. Make port 843 the default once 2. is implemented.
4. Write unit tests.
5. Better npm integration so installation is via npm.

License

All source code is distributed with a Creative Commons attribution and share-alike license.