auth

Skill: Auth (sandbox-side, sidecar-served)

Use when the user says something like "add login", "users need to sign in", "I want auth", "gate this behind a user account". The auth surface (login / signup / OAuth / sessions) is NOT something you build. Read this whole page before touching auth code.

How auth works on agentry

When the operator runs agentry auth enable on their CLI, every sandbox in that profile gets:

1. A database binding (postgres, mysql, or mongodb). Reachable via DATABASE_URL, POSTGRES_URL, MYSQL_URL, or MONGODB_URI.
2. The authproxy sidecar baked into the runtime image. When project_start spawns your app, authproxy sits in front of it:

external --(:3000)-->  authproxy  --(127.0.0.1:3001)-->  your app

Port discipline corollary (CONTRACT.md rule 1): because the sidecar owns the public port, your start_command must NOT pass --port / -p — your app reads the PORT env var (it will be 3001 when auth is on). A hard-coded port collides with the sidecar and dies with address already in use. The scaffolded start_command already does this; don't undo it.

If the auth surface itself misbehaves (403s on /auth/login, signup loops, session not sticking): that is PLATFORM territory (CONTRACT rule 5). Capture project_logs, report it to the user, and STOP. Do not write warmup routes, do not edit ports, do not set competing cookies from app code.

1. The sidecar serves the entire auth surface itself:

   • GET /auth/login — login form
   • POST /auth/login — credentials -> session cookie
   • GET /auth/signup — signup form
   • POST /auth/signup — new user -> session cookie
   • POST /auth/logout — clear session
   • GET /auth/me — JSON of the current user (or 401)
   • GET /auth/oauth/<provider>/start — OAuth flow start
   • GET /auth/oauth/<provider>/callback — OAuth callback

   Configured providers (when the operator wired them): google, github, microsoft, apple, generic-oidc.