Wombat Dressing Room

Google's npm registry proxy. Designed to reduce the attack surface of npm packages.

What it does

• You publish to Wombat Dressing Room, and it enforces additional security rules, before redirecting to registry.npmjs.org.

• Publishes are made from a single npm account with 2FA enabled (a bot account).

• Publishes can be made using the npm CLI, by making Wombat Dressing Room the default registry (npm config set registry https://external-project.appspot.com).

Deployment

This service is deployed in 2 distinct services: an external service for registry access; and a protected service for authentication/authorization (you can use a proxy, such as IAP, to limit access to the authentication server).

Prerequisites

Wombat Dressing Room requires:

• a Google Cloud Platform account to deploy to.
• an npm account, to act as your publication bot.
• and a GitHub OAuth Application to perform authentication and authorization.

Create an npm account

You will need to create an npm account, which will be used for publication. This account should be configured such that 2FA is enabled for authentication and publication. When you are given a QR code to scan for your authenticator app, use a QR code reader to fetch and store the secret associated with the 2FA configuration. You will also need to scan the QR code with an authenticator app, so that you can provide an OTP token to npm.

Create a GitHub OAuth Application

As well as an npm account, you must create a GitHub OAuth application. These credentials are used when performing authenication: both when logging into Wombat Dressing Room, for creating tokens, and when verifying certain types of tokens.

Note: the Authorization callback configured with the OAuth application should be the URL of the internal service, with the suffix /oauth/github.

Setup your environment

Once you've addressed the prerequisites, you should create environment files in the config/ directory populating the appropriate variables.

In order to start this service in development you need to create a config/local.env, in order to deploy you'll need an config/external.env and config/internal.env.

Internal environment variables

NPM_OTP_SECRET={the text value of the otp secret}
NPM_TOKEN={the npm token}
GITHUB_CLIENT_ID={github app id}
GITHUB_CLIENT_SECRET={github app secret}
DATASTORE_PROJECT_ID={project datastore is configured for}
LOGIN_ENABLED=yes-this-is-a-login-server
LOGIN_URL=https://project.appspot.com]
REGISTRY_URL=https://external-project.appspot.com

External environment variables

NPM_OTP_SECRET={the text value of the otp secret}
NPM_TOKEN={the npm token}
GITHUB_CLIENT_ID={github app id}
GITHUB_CLIENT_SECRET={github app secret}
DATASTORE_PROJECT_ID={project datastore is configured for}
LOGIN_ENABLED=this-is-not-enabled
LOGIN_URL=https://project.appspot.com]
REGISTRY_URL=https://external-project.appspot.com

Development environment variables

NPM_OTP_SECRET={the text value of the otp secret}
NPM_TOKEN={the npm token}
GITHUB_CLIENT_ID={github app id}
GITHUB_CLIENT_SECRET={github app secret}
DATASTORE_PROJECT_ID={project datastore is configured for}
LOGIN_ENABLED=yes-this-is-a-login-server
LOGIN_URL=http://127.0.0.1:8080
REGISTRY_URL=hhttp://127.0.0.1:8080

Deploy the application

To configure the Google App Engine services used by Wombat Dressing Room, perform an initial deployment:

1. install the gcloud command line tool, and run gcloud auth login.
2. run GCLOUD_PROJECT=my-project npm run deploy, where my-project is the project configured in Prerequisites.

Create a datastore table

The tokens used by Wombat Dressing Room are stored in a datastore table, before accessing the application for the first time you should run:

GCLOUD_PROJECT=my-project npm run create-indexes

To populate this datastore schema.

Note: it takes datastore a while to initialize the first time you run the application. You can view the status of index creation in the Cloud Console.

Protect your application with IAP

Wombat Dressing Room consists of an internal application, used for authorization, and an external app, used for proxing to npm. You should limit access to the internal application, a great way to do so is with IAP: configuring the default application, such that only select accounts have access; and configuring the external application with the allUsers group, such that anyone can access the proxy.

Developing the service locally

Populate config/local.env, and run:

npm run develop

Deploying updates

Populate config/external.env, and config/internal.env, and run:

npm run deploy

Contributing

Contributions welcome! See the Contributing Guide.

License

Apache Version 2.0