Passepartout API

These files generate the API for the Passepartout client.

Installation

Requirements

• Node.js

Testing

Install the package:

npm install

Fetch the infrastructure of a provider from mocks:

npm run fetch hideme

or from the real provider API:

npm run fetch hideme 1

Run the tests against the mocks:

npm test

Contributing

The latest target is api/v6, perform the steps below in that folder.

New providers

index.json

The first step is a new entry in index.json following the Provider format. The metadata is a map of maps, where the key is the module type that the provider supports. At the time of writing, only the OpenVPN type is recognized.

Example:

{
    "id": "myprovider",
    "description": "My Provider",
    "metadata": {
        "OpenVPN": {}
    }
}

getInfrastructure()

Next, you need to create a providers/myprovider.js script, i.e. named after your provider identifier. Here, you return the servers infrastructure as a ProviderInfrastructure from a JavaScript function called getInfrastructure(), finally encapsulated in a APIEngine.ScriptResult.

Example:

{
    response: {
        presets: [],
        servers: []
    }
}

where presets and servers are arrays of ProviderPreset and ProviderServer, respectively. More on the templateData field below.

You now have two options:

1. Build the infrastructure statically, like in TunnelBear
2. Fetch the response of a provider public API with the getJSON(url) API built-in, then convert it to the infrastructure format, like in Hide.me

Eventually, you will be able to generate your infrastructure JSON with:

npm run fetch myprovider

If this sounds complicated, comparing your output with the one you get from other established providers will help.

Presets

The format of ProviderPreset.templateData is a Base64-encoded JSON whose format depends on ProviderPreset.moduleType. If the module type is OpenVPN, then the expected template format is OpenVPNProviderTemplate, where the inner OpenVPN configuration follows the OpenVPN.Configuration structure.

Example:

{
    providerId: "My Provider",
    presetId: "mypreset",
    description: "My Preset",
    moduleType: "OpenVPN",
    templateData: jsonToBase64({
        configuration: {
            "ca": "...PEM here...",
            "cipher": "AES-256-CBC",
            "tlsWrap": openVPNTLSWrap("auth", "...static key here...")
        },
        endpoints: [
            "UDP:20000", "UDP:30000", "TCP:40000"
        ]
    })
}

where jsonToBase64(json) and openVPNTLSWrap(strategy, key) are API built-ins.

Unit tests

It's highly desirable that you add some basic unit tests in test/providers. You may refer to the existing tests, they should be pretty straightforward.

License

Copyright (c) 2025 Davide De Rosa. All rights reserved.

This project is licensed under the MIT.

Contributing

By contributing to this project you are agreeing to the terms stated in the Contributor License Agreement (CLA).

Contacts

Twitter: @keeshux

Website: passepartoutvpn.app