screepsmod-auth

2.8.2 verified Sat Apr 25 auth: no javascript

Screepsmod-auth is a mod for the Screeps private server that adds user/password authentication, enabling login via the API and web form. Version 2.8.2 is current, with low release cadence. It supports password setting via Steam client, server CLI, and GitHub OAuth. Configurable initial CPU and spawn blocking. Differentiates from default Steam-only auth by allowing custom credentials and GitHub login.

Common errors

error Error: Cannot find module 'screepsmod-auth' ↓

cause Module not installed or wrong path

fix

Run 'npm install screepsmod-auth' in your server folder

error TypeError: setPassword is not a function ↓

cause Importing setPassword incorrectly (e.g., default import instead of named)

fix

Use 'import { setPassword } from 'screepsmod-auth''

error Error: Github OAuth callback URL mismatch ↓

cause Callback URL does not match GitHub app configuration

fix

Ensure callback URL ends with '/api/auth/github/return' and matches exactly

error Error: spawn placement blocked ↓

cause preventSpawning set to true in config and user not whitelisted

fix

Set 'preventSpawning = false' in [auth] config or whitelist user

Warnings

breaking Removed default export in v2; only named exports available. ↓

fix Use named imports: import { setPassword, authUser, config } from 'screepsmod-auth'

deprecated CommonJS require() still works but ESM is recommended for future compatibility. ↓

fix Use ES module imports: import { ... } from 'screepsmod-auth'

gotcha Passwords set via web form require Steam client initial account creation first. ↓

fix Open Steam client once to create initial account before setting password via web.

gotcha GitHub OAuth callback URL must exactly match the registered callback on GitHub. ↓

fix Set callback URL to /api/auth/github/return on your server, e.g., https://screeps.mydomain.com/api/auth/github/return

deprecated The .screepsrc ini config is deprecated in favor of environment variables. ↓

fix Use environment variables GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, etc.

Install

npm install screepsmod-auth

yarn add screepsmod-auth

pnpm add screepsmod-auth

Imports

authUser
wrong
```
import authUser from 'screepsmod-auth'
```
correct
```
import { authUser } from 'screepsmod-auth'
```
authUser is a named export, not default. Used in config.auth.authUser.

setPassword

wrong

const setPassword = require('screepsmod-auth').setPassword

correct

import { setPassword } from 'screepsmod-auth'

ESM import; CommonJS require pattern still works but ESM is preferred.

config

wrong

import { default as config } from 'screepsmod-auth'

correct

import { config } from 'screepsmod-auth'

config is a named export, not default.

Quickstart

Shows basic usage: set a password via CLI, and configure custom authUser function.

import { setPassword } from 'screepsmod-auth';

// Via CLI: npx screeps cli
// Then run: setPassword('Username', 'YourDesiredPassword')

// Or in server config:
import { config } from 'screepsmod-auth';
config.auth.authUser = async (username, password) => {
  // custom auth logic
  return username === 'admin' && password === 'secret' ? { username } : false;
};