This release is a pre-release and may not be stable for production use.
h4ckath0n
Ship hackathon products fast, with secure-by-default auth, RBAC, Postgres readiness, and built-in LLM tooling.
h4ckath0n is an opinionated Python library that makes it hard to accidentally ship insecure glue code during a hackathon.
What you get by default
- API: FastAPI app bootstrap with OpenAPI docs
- Auth: passkey (WebAuthn) registration and login – no passwords required
- AuthZ: built-in RBAC with
userandadminroles, plus scoped permissions via JWT claims - Database: SQLAlchemy 2.x + Alembic, works with SQLite (zero-config dev) and Postgres (recommended for production)
- LLM: built-in LLM client wrapper (OpenAI SDK) with safe defaults and redaction hooks
- Observability: opt-in LangSmith / OpenTelemetry tracing with trace ID propagation
- Config: environment-driven settings via pydantic-settings
Password auth and Redis-based queues/caching are available as optional extras.
Installation
Recommended (uv)
uv add h4ckath0n
Optional extras:
uv add "h4ckath0n[password]" # Argon2-based password auth (off by default)
uv add "h4ckath0n[redis]" # Redis support
pip
pip install h4ckath0n
Scaffold a full-stack project
npx h4ckath0n my-app
Quickstart
from h4ckath0n import create_app
app = create_app()
Run:
uv run uvicorn your_module:app --reload
Open docs at /docs (Swagger UI). Passkey auth routes are mounted automatically.
Auth: passkeys by default
h4ckath0n uses passkeys (WebAuthn) as the default authentication method. No passwords, no email required.
How it works
- Register:
POST /auth/passkey/register/start→ browser creates a passkey →POST /auth/passkey/register/finish→ account created, tokens returned. - Login:
POST /auth/passkey/login/start→ browser signs with passkey →POST /auth/passkey/login/finish→ tokens returned. Username-less by default. - Add passkey: authenticated users can add more passkeys via
POST /auth/passkey/add/start+POST /auth/passkey/add/finish. - Revoke passkey:
POST /auth/passkeys/{key_id}/revoke– but cannot revoke the last active passkey (returnsLAST_PASSKEYerror).
ID scheme
- User IDs: 32-char base32 string starting with
u(e.g.,u3mfgh7k2n4p5q6r7s8t9v0w1x2y3z4a) - Internal key IDs: 32-char base32 string starting with
k - The browser's WebAuthn
credentialIdis stored separately and used for signature verification.
Secure-by-default endpoint protection
Protect an endpoint (requires a logged-in user):
from h4ckath0n import create_app
from h4ckath0n.auth import require_user
app = create_app()
@app.get("/me")
def me(user=require_user()):
return {"id": user.id, "role": user.role}
Admin-only endpoint:
from h4ckath0n.auth import require_admin
@app.get("/admin/dashboard")
def admin_dashboard(user=require_admin()):
return {"ok": True}
Scoped privileges (JWT claim scopes):
from h4ckath0n.auth import require_scopes
@app.post("/billing/refund")
def refund(user=require_scopes("billing:refund")):
return {"status": "queued"}
Auth routes
h4ckath0n mounts these routes by default:
Passkey (default)
POST /auth/passkey/register/start– begin passkey registration (creates account)POST /auth/passkey/register/finish– complete registration (returns access + refresh tokens)POST /auth/passkey/login/start– begin passkey login (username-less)POST /auth/passkey/login/finish– complete login (returns access + refresh tokens)POST /auth/passkey/add/start– begin adding a passkey (authenticated)POST /auth/passkey/add/finish– complete adding a passkey (authenticated)GET /auth/passkeys– list current user's passkeys (authenticated)POST /auth/passkeys/{key_id}/revoke– revoke a passkey (authenticated, blocked if last)
Token management
POST /auth/refresh– rotate refresh token, get new access tokenPOST /auth/logout– revoke refresh token
Password auth (optional extra)
Only available when h4ckath0n[password] is installed AND H4CKATH0N_PASSWORD_AUTH_ENABLED=true:
POST /auth/register– create account with email + passwordPOST /auth/login– authenticate with email + passwordPOST /auth/password-reset/request– request password resetPOST /auth/password-reset/confirm– confirm password reset
Database
Zero-config default: SQLite is used if no database URL is provided.
To use Postgres (recommended for production):
H4CKATH0N_DATABASE_URL=postgresql+psycopg://user:pass@host:5432/dbname
The psycopg[binary] driver is included by default – no extra install needed.
LLM
h4ckath0n includes LLM tooling by default. Set OPENAI_API_KEY and use:
from h4ckath0n.llm import llm
client = llm()
resp = client.chat(
system="You are a helpful assistant.",
user="Summarize this in one sentence: ...",
)
print(resp.text)
Fails gracefully with a clear error message when OPENAI_API_KEY is not set.
Configuration
Everything is environment-driven (prefix H4CKATH0N_):
| Variable | Default | Description |
|---|---|---|
H4CKATH0N_ENV |
development |
development or production |
H4CKATH0N_DATABASE_URL |
sqlite:///./h4ckath0n.db |
Database connection string |
H4CKATH0N_AUTH_SIGNING_KEY |
(ephemeral in dev) | JWT signing key (required in production) |
H4CKATH0N_RP_ID |
localhost (dev only) |
WebAuthn relying party ID (required in production) |
H4CKATH0N_ORIGIN |
http://localhost:8000 (dev only) |
WebAuthn expected origin (required in production) |
H4CKATH0N_WEBAUTHN_TTL_SECONDS |
300 |
Challenge expiry time (seconds) |
H4CKATH0N_USER_VERIFICATION |
preferred |
WebAuthn user verification requirement |
H4CKATH0N_ATTESTATION |
none |
WebAuthn attestation preference |
H4CKATH0N_PASSWORD_AUTH_ENABLED |
false |
Enable password auth routes (requires [password] extra) |
H4CKATH0N_BOOTSTRAP_ADMIN_EMAILS |
[] |
JSON list of emails that get admin role on registration |
H4CKATH0N_FIRST_USER_IS_ADMIN |
false |
First registered user becomes admin (dev convenience) |
OPENAI_API_KEY |
— | OpenAI API key for the LLM module |
In development mode, missing signing keys and WebAuthn settings generate ephemeral/localhost defaults with warnings.
In production mode, missing critical secrets and RP_ID/ORIGIN cause a hard error.
Observability (opt-in)
Enable end-to-end tracing across FastAPI requests, LangGraph nodes, tool calls, and LLM calls.
Enable LangSmith tracing
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=...
LANGSMITH_PROJECT=your-project-name
Trace IDs
When observability is enabled, h4ckath0n attaches X-Trace-Id to all responses:
from h4ckath0n import create_app
from h4ckath0n.obs import init_observability
app = create_app()
init_observability(app)
Development
git clone https://github.com/BTreeMap/h4ckath0n.git
cd h4ckath0n
uv sync
uv run pytest
Quality gates:
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest
Build:
uv build
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for h4ckath0n 0.1.1.dev20260210074504
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| h4ckath0n-0.1.1.dev20260210074504.tar.gz | 255.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| h4ckath0n-0.1.1.dev20260210074504-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 285.7 kB
Release files / h4ckath0n-0.1.1.dev20260210074504.tar.gz
| Download URL | h4ckath0n-0.1.1.dev20260210074504.tar.gz |
|---|---|
| Size | 255.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eada291b54433e199073d3cdcca5905f8330992c370a1129052579dce8491d6c
|
|
BLAKE2b-256 checksum How to use checksums |
dbe123f0a91f6ac65ec87f9ec9da8314f3c28878b5c3167b11d0f5affb22f0ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 10, 2026.
Transparency logRelease files / h4ckath0n-0.1.1.dev20260210074504-py3-none-any.whl
| Download URL | h4ckath0n-0.1.1.dev20260210074504-py3-none-any.whl |
|---|---|
| Size | 29.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
44d7add95b4a5e947e76126f809287d6aaf2d20417b2fc374622720b3fc3b76f
|
|
BLAKE2b-256 checksum How to use checksums |
759e4fe99fac00dc19733998702a2825199599f9037897f5b380041f81be9172
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 10, 2026.
Transparency log
