Authentication

ShipQ includes a full authentication system that you can generate with a single command. It produces database migrations, handlers, middleware, tests, and optional OAuth integrations — all wired into the compiler chain.

Generating Auth

shipq auth

This command generates:

• Migrations for organizations, accounts, and sessions tables
• Handlers in api/auth/ for login, logout, and session management (/auth/login, /auth/logout, /auth/me)
• Cookie-based session management with signed cookies (COOKIE_SECRET) and server-side sessions stored in the database
• Auth middleware that protects routes by default
• Generated tests in api/auth/spec/ that verify the full auth flow

After generating auth, run:

go mod tidy
shipq migrate up

Verify it works

Run the generated auth tests:

go test ./api/auth/spec/... -v -count=1

Adding Signup

Auth alone gives you login/logout/session management, but no user registration. To add a signup endpoint:

shipq signup

This generates a POST /auth/signup handler that creates an organization and account in a single transaction.

Note

shipq signup must be run after shipq auth — it builds on top of the auth system’s migrations and middleware.

Route Protection

After running shipq auth, your shipq.ini includes:

[auth]
protect_by_default = true

When protect_by_default = true, all handlers generated by shipq resource require authentication unless you explicitly pass --public:

# Auth-protected (default)
shipq resource pets all

# Public (no auth required)
shipq resource pets all --public

Protected routes automatically:

• Read and verify the signed session cookie from the request
• Look up the session in the database and reject expired or missing sessions with 401 Unauthorized
• Make the authenticated user’s account and organization available in the handler context

Generated tests for protected resources include both authenticated CRUD tests and 401 rejection tests.

OAuth Integration

ShipQ supports adding OAuth login providers on top of the base auth system.

Google OAuth

shipq auth google

This generates:

• A GET /auth/google endpoint that initiates the OAuth flow
• A GET /auth/google/callback endpoint that handles the OAuth callback
• Account linking logic (if a user with the same email already exists, the accounts are linked)

Required environment variables:

Variable	Description
GOOGLE_CLIENT_ID	Your Google OAuth client ID
GOOGLE_CLIENT_SECRET	Your Google OAuth client secret
GOOGLE_REDIRECT_URL	The callback URL (e.g., http://localhost:8080/auth/google/callback)

GitHub OAuth

shipq auth github

Same pattern as Google OAuth, with GitHub-specific endpoints at /auth/github and /auth/github/callback.

Required environment variables:

Variable	Description
GITHUB_CLIENT_ID	Your GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	Your GitHub OAuth app client secret
GITHUB_REDIRECT_URL	The callback URL (e.g., http://localhost:8080/auth/github/callback)

Multiple Providers

You can add multiple OAuth providers. Each provider links to the same account system — if a user signs up with email/password and later logs in with Google using the same email, the accounts are linked automatically.

shipq auth
shipq signup
shipq auth google
shipq auth github

Email Verification & Password Reset

If you have the workers system set up, you can add email verification and password reset flows:

shipq email

This command:

• Requires shipq auth to have been run first
• Requires shipq workers to have been run first (emails are sent as background jobs)
• Generates email verification and password reset handlers
• Generates email templates and sending logic via the worker queue

How Auth Fits the Compiler Chain

Auth is deeply integrated with ShipQ’s compiler chain:

1. Schema compiler: shipq auth creates migrations that shipq migrate up compiles into typed schema bindings. The organizations, accounts, and sessions tables become available in shipq/db/schema/schema.go.

2. Query compiler: Auth generates query definitions in querydefs/ that shipq db compile turns into typed query runners for login, session lookup, account creation, etc.

3. Handler compiler: Auth handlers register themselves in the handler registry. When you run shipq handler compile, they’re included in the generated server wiring, OpenAPI spec, test client, and TypeScript clients.

4. Resource generation: When protect_by_default = true, shipq resource generates handlers that use the auth middleware, and the handler compiler generates 401 tests alongside the CRUD tests.

Generated File Ownership

Files with the zz_generated_ prefix or the // Code generated by shipq. DO NOT EDIT. header are overwritten on every compile. You can safely edit handler files that don’t have these markers — they’re yours to customize.

The main files you’d typically customize:

• Handler logic in api/auth/*.go (non-generated files)
• Customizing the signup flow (e.g., adding profile fields)
• Adjusting session expiry or cookie settings

Testing Auth

ShipQ generates comprehensive auth tests. After running shipq auth and shipq handler compile, your test suite includes:

• Login flow tests: valid credentials, invalid credentials, missing fields
• Session management tests: token validation, logout, /auth/me
• 401 rejection tests: unauthenticated access to protected routes
• RBAC tests: role-based access control (when roles are configured)
• OAuth tests: provider login flow, account linking

Run all auth-related tests:

go test ./api/auth/spec/... -v -count=1

Or run your entire test suite:

go test ./... -v