|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build & Run |
| 6 | + |
| 7 | +```bash |
| 8 | +go build -o auth ./cmd/auth # build binary |
| 9 | +go vet ./... # lint |
| 10 | +``` |
| 11 | + |
| 12 | +No test files exist in this codebase. |
| 13 | + |
| 14 | +### Required environment variables |
| 15 | + |
| 16 | +| Variable | Description | |
| 17 | +|---|---| |
| 18 | +| `SQL_URL` | PostgreSQL connection string | |
| 19 | +| `OAUTH2_CLIENT_ID` | Google OAuth app client ID | |
| 20 | +| `OAUTH2_CLIENT_SECRET` | Google OAuth app client secret | |
| 21 | +| `PORT` | Listen port (default: `8080`) | |
| 22 | + |
| 23 | +## Architecture |
| 24 | + |
| 25 | +This is a minimal OAuth2 authentication service for Deploys.app. It acts as an OAuth2 authorization server backed by Google as the identity provider. |
| 26 | + |
| 27 | +### Entry point |
| 28 | + |
| 29 | +`cmd/auth/main.go` reads env vars, opens a PostgreSQL connection, registers handlers on a `http.ServeMux`, wraps it with `pgctx.Middleware` (binds the DB to each request context), and calls `http.ListenAndServe`. |
| 30 | + |
| 31 | +### HTTP endpoints |
| 32 | + |
| 33 | +| Method | Path | Handler | Purpose | |
| 34 | +|---|---|---|---| |
| 35 | +| `GET` | `/` | `RedirectHandler` | Validates the OAuth2 client and redirects the user to Google | |
| 36 | +| `GET` | `/callback` | `CallbackHandler` | Receives Google's code, exchanges it for an ID token, issues an internal auth code | |
| 37 | +| `POST` | `/token` | `TokenHandler` | Exchanges client credentials + internal code for a long-lived user token | |
| 38 | +| `POST` | `/revoke` | `RevokePostHandler` | Deletes a user token by its hash | |
| 39 | + |
| 40 | +### Database access pattern |
| 41 | + |
| 42 | +`github.com/acoshift/pgsql` / `pgctx` is the only DB layer. Calling `pgctx.Middleware(db)` stores the `*sql.DB` in the request context; handlers then call `pgctx.Exec(ctx, ...)` or `pgctx.QueryRow(ctx, ...)` directly — there is no ORM or repository struct. |
| 43 | + |
| 44 | +All DB logic lives in `oauth2.go` (session/code helpers) and `token.go` (token hashing and persistence). |
| 45 | + |
| 46 | +### Session & token lifecycle |
| 47 | + |
| 48 | +- **OAuth2 sessions** (`oauth2_sessions`) — created by `RedirectHandler`, deleted on first read by `CallbackHandler`. 1-hour TTL enforced in the WHERE clause. |
| 49 | +- **OAuth2 codes** (`oauth2_codes`) — created by `CallbackHandler`, consumed atomically (DELETE … RETURNING) by `TokenHandler`. 1-hour TTL. |
| 50 | +- **User tokens** (`user_tokens`) — 7-day TTL, stored as SHA-256 hashes. Revoked by `RevokePostHandler`. |
| 51 | + |
| 52 | +### Key decisions |
| 53 | + |
| 54 | +- No framework — plain `net/http` + `http.ServeMux`. |
| 55 | +- No test files; no graceful shutdown / signal handling. |
| 56 | +- Google is the only upstream identity provider (hardcoded endpoints in `handler.go`). |
| 57 | +- Docker image uses `gcr.io/distroless/static` for a minimal runtime. |
| 58 | +- CI builds and pushes to `registry.moonrhythm.io/deploys-app/auth:<git-sha>`. |
0 commit comments