ssn/README.md

This library provides various methods for fetching releases from SWTOR’s patch server CDN and installing them. You can use it to write your own patch program. If you just want to install patches without having to do any programming, use the command-line tools from the [ssn-tools](/swtor/ssn-tools) repository.

# Installation

For this tool to work, `tsc` and `tslint` must be globally available, e.g. by running:

```bash
sudo npm install -g typescript tslint
```

In the project where you want to use this library, add the following to your `package.json` file:

```json
{
  "dependencies": {
    "ssn": "git+https://git.jedipedia.net/swtor/ssn.git"
  }
}
```

Then run:

```bash
npm install
```

# Usage
To import the functions into your Node.js application:

```ts
import * as ssn from 'ssn';

(async function() {
  const manifestContents = await ssn.getManifest('assets_swtor_main');
  console.log(manifestContents);

  const solidpkgContents = await ssn.getSolidpkg('assets_swtor_main', 126, 127);
  console.log(solidpkgContents);
}())
```

# Development

To work with the repository locally:

```bash
sudo npm install -g typescript tslint
git clone https://git.jedipedia.net/swtor/ssn.git
cd ssn
npm install && npm start
```

# License

Copyright (C) 2018 Jedipedia.net

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

# Introduction
SWTOR’s patcher uses technology licensed from Solid State Networks (SSN). However, SWTOR does not use the GUI software from SSN; instead the developers wrote their own patch deploy pipeline which interfaces with the command line tools from SSN.

Also, SWTOR does not use all features offered by SSN. Notably, for public-facing products they do not use the peer-to-peer download of patches; instead all patches are downloaded from a CDN. In addition, they do not use the `upcoming` feature where you can preload a future patch before it is released.

Instead of the SSN patcher, the live game (but not the PTS) can also be installed via BitRaider. We do not cover BitRaider since understanding SSN is enough to install all patches.

## Terminology
SSN uses the following terms; make sure you are familiar with them since we use them as well in documentation and in code.

- __`product`__: SWTOR is split into multiple products. That way, you can choose to only install part of SWTOR. For example, if you install the products `assets_swtor_main` and `assets_swtor_en_us`, you only have the English-language live client files and no other languages and no PTS.
- __`release`__: Colloquially, this is known as a “patch” or “Game Update”. For example, release `264` in product `assets_swtor_main` refers to Game Update 5.2.0. However, not every release can be mapped to a “patch”; sometimes there are multiple releases between two actual “patches”, e.g. because of build errors or because after a release is built, an urgent issue crops up that requires a hotfix before the “patch” can be pushed to the live servers. A release is always an integer starting at `0`.
- __`patch`__: In the SSN sense, a patch refers to the difference between two releases. For example, `263to264` is a patch that can be used to update a product from release `263` to release `264`. The first number is called `from` while the second number is `to`. In order to install a patch, the release given in the `from` number must already be installed on your disk, with one exception: If the `from` number is `-1`, e.g. in patch `-1to0`, the patch does not store the differences but it has the full file contents to allow for a fresh install.
- __`environment`__: An environment consists of multiple products. For example, the live environment (`swtor`) has products like `assets_swtor_main` while the PTS environment (`publictest`) has `assets_swtor_test_main`.
- __`manifest`__: Each product has a manifest, a single file that lists all releases and all patches, and specifies which release is the current release (that the launcher must install).

# SSN file format and encryption

All files used by SSN are password-protected .zip files with a .exe header. The files are stored in the .zip section, while the .exe header (and the signatures at the end) are used to verify the integrity of the file. We are not interested in checking the integrity, so we only look at the .zip sections. Check the [.zip specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) for more information on the .zip format.

For each file, the extra field contains the following information:

- For password protected files, the password needed to decrypt the file. The password itself is encoded and even if you have decoded it, it is usually in binary. Most .zip software only accepts textual passwords, so I recommend writing a custom .zip reader.
- Whether this file is stored in full, or whether only the differences are stored in vcdiff/xdelta3 encoding. Also flags whether a file was deleted, and it includes the hashes of both the old and the new file.

## Manifests (`.patchmanifest`)

A .patchmanifest SSN file contains a single file `manifest.xml` which includes a list of releases and patches, and specifies which manifest is the current one.

## Patches (`.solidpkg`)

A .solidpkg file contains a single file `metafile.solid`, which is in Bencode format (similar to .torrent files) and includes the names, sizes and hashes of all files with the patch data (.zip, .z01, .z02 etc.).

## Version files (`.version`)

Once a patch is installed, you can look into the .version file to figure out which release it is, and use the hashes to verify that the installation is correct.

# File download and CDN

Manifests are hosted on manifest.swtor.com, while patches are hosted on cdn-patch.swtor.com. They can only be downloaded via HTTP (port 80) but the lack of HTTPS is not an issue since the files are integrity-checked via their included signatures.

Manifests can be downloaded as follows: `http://manifest.swtor.com/patch/${product}.patchmanifest`

Then knowing which patch you need, you can get the patch as follows: `http://cdn-patch.swtor.com/patch/${product}/${product}_${from}to${to}.solidpkg`

In cases where the environment is part of the product name, the URL is slightly different since there is a folder for the environment: `http://cdn-patch.swtor.com/patch/${environment}/${product}/${product}_${from}to${to}.solidpkg`

# Appendix

## Environments used by SWTOR

Currently, the following three environments are used:

- __`swtor`__: The live game, including the European and North American servers. Open to all players and the default environment when logging into the launcher.
- __`publictest`__: The Public Test Server to allow players to test upcoming content. Open to players most of the time, unless the testing is under NDA, in which case only accounts invited to the test have access.
- __`liveqatest`__: The environment where QA can test upcoming patches before they are deployed to the live servers. Not accessible to players.

Previously, the following environments were also used:

- __`betatest`__: The client used during the closed beta (2011 and earlier) to play the game.
- __`cstraining`__: No longer used.
- __`liveeptest`__: No longer used.
- __`squadron157`__: The client used during the early closed beta by the Squadron157 testing group to play the game.

## Products used by SWTOR

SWTOR uses the following products:

- __`assets_swtor_de_de`__: German language files for the live environment.
- __`assets_swtor_en_us`__: English language files for the live environment.
- __`assets_swtor_fr_fr`__: French language files for the live environment.
- __`assets_swtor_main`__: Main game data for the live environment.
- __`assets_swtor_test_de_de`__: German language files for the PTS environment.
- __`assets_swtor_test_en_us`__: English language files for the PTS environment.
- __`assets_swtor_test_fr_fr`__: French language files for the PTS environment.
- __`assets_swtor_test_main`__: Main game data for the PTS environment.
- __`eualas`__: End user access and license agreement, and other legal documents you need to accept in the launcher before you can play the game.
- __`movies_de_de`__: Intro movies by Blur in German language.
- __`movies_en_us`__: Intro movies by Blur in English language.
- __`movies_fr_fr`__: Intro movies by Blur in French language.
- __`patcher2014`__: The old launcher, now replaced by `patcher2017` but still available for download.
- __`patcher2017`__: Current version of the launcher, used to download and install patches.
- __`retailclient_{environment}`__: The client used to play the game, e.g. `retailclient_swtor` or `retailclient_publictest`.

In addition, there are a few private products which are only reachable through BioWare’s VPN and are not publicly accessible:

- __`biomon_{environment}`__: The `Biomongoose` tool, possibly to monitor performance like CPU and memory usage.
- __`byftools_{environment}`__: Unknown tools `ByfTools` and `iPen`, might be related to Photoshop or other designer tools.
- __`heroblade_{environment}`__: The IDE used for editing the game, either by placing new objects into the game world or editing scripts.
- __`morpheme_{environment}`__: Morpheme is a middleware used for character animations. Only available in the `cstraining` and `liveqatest` environments.
- __`patcher`__: The old launcher before the 2014 revamp. No longer in use.
- __`playerclient_{environment}`__: A client to play the game, used by the devs instead of `retailclient`. Has a console and integrates with HeroBlade.
- __`repositoryassistant_{environment}`__: unknown
- __`repositorybrowser_{environment}`__: The repository browser interfaces with HeroBlade to load 3D models, textures and other assets.
- __`toolshub_{environment}`__: Used to launch more tools; most likely SpeedTree, WWise and other middleware.
- __`visualizer_{environment}`__: Also known as `VANViewer`; possibly the tool mentioned by Georg Zoeller in his 2011 GDC talk.