Project Structure

Last Updated: 2026-10-29

The dracory/auth library is organized into focused packages for clarity and maintainability.

Directory Layout

dracory/auth/
├── types/              # Public: configs, interfaces, Method, PostAuthHooks
├── utils/              # Utility functions (internal use)
├── internal/           # Internal implementation (not public API)
│   ├── api/           # JSON endpoint handlers (one dir per endpoint)
│   ├── core/          # Shared post-auth pipeline
│   ├── emails/        # Default email templates
│   ├── helpers/       # Internal helpers
│   ├── links/         # Route path helpers
│   ├── middlewares/   # Internal middleware (CSRF, rate limit)
│   ├── rules/         # Reusable rule checks (throttles, validation, registration policy)
│   ├── testutils/     # Shared test fixtures
│   └── ui/            # Server-rendered pages (one dir per page)
├── examples/           # Runnable example apps
│   ├── passwordless/
│   ├── usernamepassword/
│   └── authknight/
├── docs/               # Documentation (markdown → generated HTML site)
│   ├── peers/         # Feature comparisons vs peer solutions
│   ├── proposals/     # Design proposals
│   └── tasks/         # Implementation tasks (pending/done)
└── *.go               # Public API: constructors, method adapters, middleware

types/ — Public API

• auth_interfaces.go — AuthSharedInterface, AuthOtpInterface, AuthPasswordInterface, AuthAuthKnightInterface
• config_shared.go — ConfigShared (endpoint, cookies, callbacks, rate limiting) embedded by all configs
• config_passwordless.go / config_username_and_password.go / config_authknight.go — per-method configs
• method.go — Method interface + RouteProvider (multi-method composition)
• post_auth.go — PostAuthHooks + SessionInterface
• session.go, cookie_config.go, observability.go, user_auth_options.go, messages.go, constants.go, password.go

internal/api/ — Endpoint handlers

api_login · api_login_code_verify · api_magic_link_send · api_magic_link_callback · api_register · api_register_code_verify · api_logout · api_password_restore · api_password_reset · api_authenticate_via_username · api_authknight_callback · api_impersonate_start · api_impersonate_stop

Each subdirectory holds the handler, a Dependencies struct (or …WithAuth wrapper taking the public interface), and tests.

internal/ui/ — Page handlers

page_login · page_magic_link · page_login_code_verify · page_register · page_register_code_verify · page_logout · page_password_restore · page_password_reset · shared (page scaffold, RedirectAuthKnightIfActive)

Pages are built with github.com/dracory/hb, styled with Bootstrap, and take the auth interface so FuncLayout and page hooks apply consistently.

internal/ support packages

• core/ — PostAuth: the shared post-authentication pipeline all methods funnel through when hooks are configured
• rules/ — reusable checks (per-email send throttle, validation, registration policy: ProfileCompletionRule, RegisterFirstRule, VerifiedEmailKeyRule)
• links/ — endpoint path helpers
• emails/ — default plain email bodies
• middlewares/, helpers/, testutils/

Root package

• new_passwordless_auth.go, new_username_and_password_auth.go, new_authknight_auth.go — constructors (validate config, wire defaults)
• multi_method.go — MultiMethodAuth, NewMultiMethodAuth, and the built-in types.Method adapters (otpMethod, magicLinkMethod, passwordMethod, authKnightMethod)
• auth_implementation*.go — the implementation struct: getters/setters, API/page delegation, cookies
• Middleware + cookie helpers (AuthCookieSet, CookieName, …)

Design Principles

1. Separation of concerns — types, rules, API handlers, UI handlers, and the post-auth pipeline are distinct packages
2. Internal encapsulation — internal/ is not importable; public surface is root package + types/
3. Thin facade — the root package delegates to internal packages
4. Composable methods — types.Method + RouteProvider let methods ship pages, ajax, callbacks, and extra routes without core changes
5. Optional hooks via type assertion — new capabilities (session store, post-auth hooks, temp-key delete) attach through optional interfaces so existing AuthSharedInterface implementers don't break
6. Testability — tests live next to each component

Public vs Internal

Safe to import: github.com/dracory/auth, github.com/dracory/auth/types Do not import: github.com/dracory/auth/internal/*, github.com/dracory/auth/utils