Hack Club Auth

This is the Rails codebase powering https://auth.hackclub.com!

contributing

ask around in #idv-dev or poke nora!

avoid questions that can be answered by reading the source code, but otherwise i'd be happy to help you get up to speed :-D

kindly bin/lint your code before you submit it!

local dev setup

prerequisites

you'll need:

• ruby 3.4.4+ (i use mise to manage this)
• node.js + yarn
• postgres (see below)
• imagemagick & libvips (image processing)
• libxmlsec1 (SAML signing)

on macOS:

brew install imagemagick libvips libxmlsec1 yarn

database

easiest way is docker. if you don't have it and you're on macOS, orbstack works well enough.

docker compose -f docker-compose-dbonly.yml up -d

this gives you a postgres instance at postgresql://postgres@localhost:5432/identity_vault_development.

if you've got your own postgres running somewhere, that works too – just point at it.

environment

create a .env.development file:

DATABASE_URL=postgresql://postgres@localhost:5432/identity_vault_development

that's it for local dev – lockbox will use a deterministic dev key automatically. see environment variables below for the full list.

install & setup

bundle install
yarn install
bin/rails db:prepare
bin/rails db:seed

the seeds create a dev account with 2FA already set up. it'll print out the TOTP secret – add that to your authenticator app.

running the thing

bin/dev

if you want hot reload on css & js, also run bin/vite dev in another terminal.

logging in to the backend

1. go to http://localhost:3000/login
2. enter identity@hackclub.com
3. grab the verification code from http://localhost:3000/letter_opener
4. enter your TOTP code (from the authenticator app you set up during seeding)
5. head to http://localhost:3000/backend

the backend requires 2FA – that's why the seeds set up a TOTP for you.

environment variables

required

var	description
DATABASE_URL	postgres connection string

required in production

var	description
SECRET_KEY_BASE	rails secret key – generate with openssl rand -hex 64
LOCKBOX_MASTER_KEY	encryption key for lockbox fields – generate with openssl rand -hex 32

active record encryption

used for encrypts fields (like aadhaar data). generate these with bin/rails db:encryption:init or use random strings.

var	description
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY	primary encryption key
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY	deterministic encryption key
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT	key derivation salt

slack integration

var	description
SLACK_BOT_TOKEN	bot token (xoxb-*)
SLACK_TEAM_ID	workspace ID (T*)
SLACK_SCIM_TOKEN	SCIM API token for user provisioning
SLACK_CLIENT_ID	OAuth client ID
SLACK_CLIENT_SECRET	OAuth client secret
SLACK_SIGNING_SECRET	webhook request verification
SLACK_ADULT_WEBHOOK_URL	webhook for guardian notifications

SAML

var	description
SAML_IDP_CERT_PATH	path to SAML IdP certificate
SAML_IDP_KEY_PATH	path to SAML IdP private key

generate a self-signed cert for local dev:

openssl req -x509 -newkey rsa:2048 -keyout saml_key.pem -out saml_cert.pem -days 365 -nodes -subj "/CN=localhost"

OIDC

var	description
OIDC_SIGNING_KEY	RSA private key for JWT signing

generate an RSA key:

openssl genrsa -out oidc_key.pem 2048

then set OIDC_SIGNING_KEY to the contents of oidc_key.pem (the whole thing including the BEGIN/END lines).

email (production/staging/uat)

var	description
SES_SMTP_HOST	SES SMTP endpoint
SES_SMTP_USERNAME	SES SMTP username
SES_SMTP_PASSWORD	SES SMTP password

document storage (production)

var	description
CLOUDFLARE_R2_ENDPOINT	R2 endpoint URL
CLOUDFLARE_R2_ACCESS_KEY_ID	R2 access key
CLOUDFLARE_R2_SECRET_ACCESS_KEY	R2 secret key

other

var	description
SENTRY_DSN	error tracking
GOOGLE_PLACES_API_KEY	address autocomplete
ANALYTICS_DATABASE_URL	separate analytics DB (optional)
DISABLE_ANALYTICS	set to "true" to disable Ahoy
SOURCE_COMMIT	git commit for version display

security

this oughta go without saying, but if you find a security-relevant issue please either contact me directly or go through the security.hackclub.com flow – if you just open an issue or a PR there's a chance a bad actor sees it and exploits it before we can patch or merge.