Pre-release

This release is a pre-release and may not be stable for production use.

h4ckath0n

Ship hackathon products fast with a secure FastAPI bootstrap and passkey-first authentication.

What you get

FastAPI app factory with passkey routes mounted by default
Device signed ES256 JWT authentication and server-side RBAC (user, admin, scopes)
SQLAlchemy 2.x models with automatic table creation on startup
LLM wrapper around the OpenAI SDK with timeouts and retries
Optional password auth extra for email and password flows
Optional Redis extra that only adds the dependency, no integration is provided yet
Trace ID middleware and LangSmith environment wiring via init_observability
Full stack scaffold CLI that produces an API and web template

Installation

Recommended (uv)

uv add h4ckath0n

Optional extras:

uv add "h4ckath0n[password]"  # Argon2 based password auth
uv add "h4ckath0n[redis]"     # Redis dependency only

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

OpenAPI docs

Interactive docs live at /docs when the app is running.
Public routes like passkey start and finish work without auth.
Protected routes require an Authorization: Bearer <device_jwt> header that the web template can mint after login.

Built-in routes

GET / — welcome message confirming the app is reachable.
GET /health — returns {"status": "healthy"} for load balancer and deployment checks.

Session

GET /auth/session — returns the current user session details.

Background Jobs

GET /jobs — list jobs.
POST /jobs — enqueue a background job.
GET /jobs/{job_id} — get the status and result of a job.

Uploads

GET /uploads — list uploaded files.
POST /uploads — upload a new file.
GET /uploads/{upload_id} — get metadata for a specific upload.
GET /uploads/{upload_id}/download — download the uploaded file.

LLM Chat

POST /llm/chat — send a message to the language model.
POST /llm/chat/stream — stream responses from the language model.

Auth model

Passkeys by default

The default authentication path uses passkeys (WebAuthn). The core flows are:

POST /auth/passkey/register/start and POST /auth/passkey/register/finish
POST /auth/passkey/login/start and POST /auth/passkey/login/finish
POST /auth/passkey/add/start and POST /auth/passkey/add/finish for adding devices
GET /auth/passkeys, POST /auth/passkeys/{key_id}/revoke, and PATCH /auth/passkeys/{key_id} for management

Device signed JWTs

After login or registration, the client binds a device key and mints short lived ES256 JWTs. The server uses the kid header to load the device public key and verifies the signature and aud claim. JWTs contain only identity and time claims, no roles or scopes.

ID scheme

User IDs are 32 characters and start with u
Passkey IDs are 32 characters and start with k
Device IDs are 32 characters and start with d
Password reset tokens use UUID hex, not the base32 scheme

Secure endpoint protection

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 permissions:

from h4ckath0n.auth import require_scopes

@app.post("/billing/refund")
def refund(user=require_scopes("billing:refund")):
    return {"status": "queued"}

Password auth (optional)

Password routes mount only when the password extra is installed and H4CKATH0N_PASSWORD_AUTH_ENABLED=true.

POST /auth/register
POST /auth/login
POST /auth/password-reset/request
POST /auth/password-reset/confirm

Password auth is only an identity bootstrap. It binds a device key but does not return access tokens, refresh tokens, or cookies.

Configuration

All settings use the H4CKATH0N_ prefix unless noted.

Variable	Default	Description
`H4CKATH0N_ENV`	`development`	`development` or `production`
`H4CKATH0N_DATABASE_URL`	`sqlite:///./h4ckath0n.db`	SQLAlchemy connection string
`H4CKATH0N_AUTO_UPGRADE`	`false`	Auto-run packaged DB migrations to head on startup
`H4CKATH0N_RP_ID`	`localhost` in development	WebAuthn relying party ID, required in production
`H4CKATH0N_ORIGIN`	`http://localhost:8000` in development	WebAuthn origin, required in production
`H4CKATH0N_WEBAUTHN_TTL_SECONDS`	`300`	WebAuthn challenge TTL in seconds
`H4CKATH0N_USER_VERIFICATION`	`preferred`	WebAuthn user verification requirement
`H4CKATH0N_ATTESTATION`	`none`	WebAuthn attestation preference
`H4CKATH0N_PASSWORD_AUTH_ENABLED`	`false`	Enable password routes when the extra is installed
`H4CKATH0N_PASSWORD_RESET_EXPIRE_MINUTES`	`30`	Password reset token expiry in minutes
`H4CKATH0N_BOOTSTRAP_ADMIN_EMAILS`	`[]`	JSON list of emails that become admin on password signup
`H4CKATH0N_FIRST_USER_IS_ADMIN`	`false`	First password signup becomes admin
`OPENAI_API_KEY`	empty	OpenAI API key for the LLM wrapper
`H4CKATH0N_OPENAI_API_KEY`	empty	Alternate OpenAI API key for the LLM wrapper
`H4CKATH0N_REDIS_URL`	empty	Redis connection string
`H4CKATH0N_JOBS_INLINE_IN_DEV`	`true`	Run background jobs inline in development mode
`H4CKATH0N_JOBS_DEFAULT_QUEUE`	`default`	Default Redis queue for background jobs
`H4CKATH0N_STORAGE_BACKEND`	`local`	Storage backend
`H4CKATH0N_STORAGE_DIR`	`./.h4ckath0n_storage`	Local directory for uploaded files
`H4CKATH0N_MAX_UPLOAD_BYTES`	`52428800`	Maximum upload size in bytes (50 MiB)
`H4CKATH0N_APP_BASE_URL`	`http://localhost:5173`	Application base URL for email links
`H4CKATH0N_EMAIL_BACKEND`	`file`	Email backend: `file` or `smtp`
`H4CKATH0N_EMAIL_FROM`	`noreply@localhost`	Sender address for outgoing emails
`H4CKATH0N_EMAIL_OUTBOX_DIR`	`./.h4ckath0n_email_outbox`	File-backend email output directory
`H4CKATH0N_SMTP_HOST`	empty	SMTP server host
`H4CKATH0N_SMTP_PORT`	`587`	SMTP server port
`H4CKATH0N_SMTP_USERNAME`	empty	SMTP authentication username
`H4CKATH0N_SMTP_PASSWORD`	empty	SMTP authentication password
`H4CKATH0N_SMTP_STARTTLS`	`true`	Enable SMTP STARTTLS
`H4CKATH0N_SMTP_SSL`	`false`	Enable SMTP-over-SSL
`H4CKATH0N_DEMO_MODE`	`false`	Enable demo mode

In development, missing RP_ID and ORIGIN fall back to localhost defaults with warnings. In production, missing values raise a runtime error when passkey flows start.

Postgres readiness and migrations

Set a Postgres database URL to run against Postgres:

H4CKATH0N_DATABASE_URL=postgresql+psycopg://user:pass@host:5432/dbname

create_app() calls Base.metadata.create_all on startup.

h4ckath0n also ships an operator CLI and packaged Alembic migrations:

h4ckath0n db ping
h4ckath0n db migrate upgrade --to head --yes

If startup or db ping reports that the database schema is behind, run:

h4ckath0n db migrate upgrade --to head --yes

If startup or db ping reports that the database was initialized without Alembic versioning, run:

h4ckath0n db migrate stamp --to <baseline> --yes
h4ckath0n db migrate upgrade --to head --yes

For legacy create_all deployments in current releases, use <baseline>=head.

LLM usage

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)

The wrapper raises a RuntimeError if no API key is configured.

Observability

init_observability(app) adds an X-Trace-Id header to responses and can set LangSmith environment variables if ObservabilitySettings.langsmith_tracing is true. It does not instrument FastAPI, LangChain, or OpenAI calls by itself.

from h4ckath0n import create_app
from h4ckath0n.obs import ObservabilitySettings, init_observability

app = create_app()
init_observability(app, ObservabilitySettings(langsmith_tracing=True))

Compatibility and operational notes

Passkeys require HTTPS in production. localhost is allowed for development.
H4CKATH0N_RP_ID must match your production domain and H4CKATH0N_ORIGIN must include the scheme and host.
The last active passkey cannot be revoked. Add a second passkey first.

Development

git clone https://github.com/BTreeMap/h4ckath0n.git
cd h4ckath0n
uv sync --locked --all-extras

Quality gates:

uv run --locked ruff format --check .
uv run --locked ruff check .
uv run --locked mypy src
uv run --locked pytest -v

License

MIT. See LICENSE.

Release files for h4ckath0n 0.1.10.dev20260810

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for h4ckath0n 0.1.10.dev20260810
File	Size	Uploaded
h4ckath0n-0.1.10.dev20260810.tar.gz	507.4 kB	Aug 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for h4ckath0n 0.1.10.dev20260810
File	Interpreter	ABI	Platform	Reset
h4ckath0n-0.1.10.dev20260810-py3-none-any.whl 81.1 kB Aug 10, 2026	Python 3	none	any	Details

Total release size: 588.5 kB

Release files / h4ckath0n-0.1.10.dev20260810.tar.gz

Download URL	h4ckath0n-0.1.10.dev20260810.tar.gz
Size	507.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`9af99b6b276ea4b82c28eec45922be6ca6c2b3b3ab1104681b86414931bf1fd5`
BLAKE2b-256 checksum How to use checksums	`5bd2ad90cd4837aa4aa56edaf6389c9fae420bb41951c9b3ad7c1aad6012cebd`
Upload date	Aug 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BTreeMap/h4ckath0n
Publishing commit: github.com/BTreeMap/h4ckath0n/tree/a9f79e6c146ea29e36971ef0a5da38111cfb0ea1

Workflow

Publishing configuration: github.com/BTreeMap/h4ckath0n/blob/a9f79e6c146ea29e36971ef0a5da38111cfb0ea1/.github/workflows/publish.yml
Publishing logs: github.com/BTreeMap/h4ckath0n/actions/runs/31354126397/attempts/1

Artifact

Subject: h4ckath0n-0.1.10.dev20260810.tar.gz
SHA-256 checksum: 9af99b6b276ea4b82c28eec45922be6ca6c2b3b3ab1104681b86414931bf1fd5 Verifying attestations

Release files / h4ckath0n-0.1.10.dev20260810-py3-none-any.whl

Download URL	h4ckath0n-0.1.10.dev20260810-py3-none-any.whl
Size	81.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cfe0dda963e63bedd6ecb8a31c3fcfbe4cf9b759ced5897a98e4bf1aea2f202d`
BLAKE2b-256 checksum How to use checksums	`3acaa3803a6b3541333ae290d01602c9e92ed4f60574e57de0cb110d440efa89`
Upload date	Aug 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BTreeMap/h4ckath0n
Publishing commit: github.com/BTreeMap/h4ckath0n/tree/a9f79e6c146ea29e36971ef0a5da38111cfb0ea1

Workflow

Publishing configuration: github.com/BTreeMap/h4ckath0n/blob/a9f79e6c146ea29e36971ef0a5da38111cfb0ea1/.github/workflows/publish.yml
Publishing logs: github.com/BTreeMap/h4ckath0n/actions/runs/31354126397/attempts/1

Artifact

Subject: h4ckath0n-0.1.10.dev20260810-py3-none-any.whl
SHA-256 checksum: cfe0dda963e63bedd6ecb8a31c3fcfbe4cf9b759ced5897a98e4bf1aea2f202d Verifying attestations