Hack Club Auth Archive (April 08, 2026)

Caution

TECHNICAL AUDIT NOTICE

This repository is a static archive preserved for forensic auditing and youth safeguarding oversight.

All technical liability, privacy inquiries, or complaints regarding these operations must be directed to Hack Club's leadership and engineering staff via the contact information on the Hack Club GitHub organization or on the official Hack Club website.

Important

LEGAL NOTICE & ARCHIVE PROTOCOL

• No Support of Content: The archiver does not support, endorse, or condone any viewpoints, ideologies, or organizational practices expressed, implied, or implemented within this repository.

• No Warranties: This archive is provided "as-is" for transparency and forensic purposes; no warranties of any kind are provided regarding the functionality, safety, or legality of the contained code.

• Non-Production Warning: The archiver strictly does not condone the use of this software in a production environment and/or with real-world user data. This code implements surveillance and profiling mechanisms that may violate international privacy standards and youth safeguarding regulations.

• Purpose of Archive: This repository is maintained strictly for security and privacy audits, legal documentation, historical archival, and forensic research using simulated/synthetic data. It serves as a public interest case study in the degradation of nonprofit transparency and as a technical reference for the ethical failures of centralized youth surveillance infrastructure.

• Non-Affiliation: The archiver (the owner of this fork) is not a contributor to this project, has no affiliation with the original authors (including but not limited to [@]24c02, other Hack Club employees/contractors on this repository, Hack Club, or the Hack Foundation), and assumes no responsibility for the function or deployment of this code.

• Trademark Notice: All third-party trademarks mentioned (including but not limited to Hack Club, and The Hack Foundation) are the property of their respective owners. The archiver claims no ownership rights over any third-party trademarks mentioned herein.

Note

Any links below the divider line link to Hack Club owned/operated servers on the internet. I do not control the links below, so visit them at your own risk using appropriate cybersecurity procedures as necessary.

---

Original unchanged description below:

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.