# Authentication reference

Source: https://docs.anetos.dev/reference/auth/

Packages `auth`, `auth/password`, `auth/social` and `auth/rbac`. How-to: [Authentication](https://docs.anetos.dev/guides/authentication/index.md),
[Authorization](https://docs.anetos.dev/guides/authorization/index.md), [Roles and permissions](https://docs.anetos.dev/guides/roles-and-permissions/index.md). Settings: [configuration reference](https://docs.anetos.dev/reference/configuration/index.md#authentication).

## Setup

| API | Does |
|---|---|
| `auth.Authenticatable` | `AuthID() string` and `AuthPassword() string`, implemented by the app's user type |
| `auth.Users[U]{ByID, ByLogin, RememberToken, SetRememberToken, SetPassword, Disabled, SessionKey, SetSessionKey, TwoFactor, SetTwoFactor}` | How to find users (required: `ByID`, `ByLogin`; they return `db.ErrNotFound` or `auth.ErrUserNotFound`), store remember-me tokens and upgraded hashes; which accounts are disabled (`Disabled`); the session key sessions are bound to (`SessionKey` and `SetSessionKey`, both or neither); the two-factor state, stored encrypted (`TwoFactor` and `SetTwoFactor`, both or neither) |
| `auth.New(app, users, opts...)` | `*auth.Auth[U]` from `AUTH_*` and `APP_KEY`; needs `cache.New` first; provided to the app; once per app. Options as `NewWithConfig`'s, after its own, and `auth.WithDefaultHomeURL(path)`: `AUTH_HOME_URL`'s default |
| `auth.NewWithConfig(cfg, users, enc, opts...)` | Without an app; `auth.WithLogger`, `auth.WithInsecureCookies`, `auth.WithIssuer(name)` (two-factor setups' issuer; `auth.New` uses `APP_NAME`) |
| `auth.Migrations()` | The `api_tokens` table, for `migrate.New` |

## Middleware

| API | Does |
|---|---|
| `a.Middleware` | Makes the request's user available (from the session or a remember-me cookie); after the session middleware |
| `a.Require` | Logged-in users only: guests asking for a page are redirected to `AUTH_LOGIN_URL`; others, and every request on routes without sessions, get 401, with `WWW-Authenticate: Bearer` on routes without sessions or behind `TokenMiddleware`. Responses to logged-in users get `Cache-Control: no-store` unless the handler sets another |
| `a.Guest` | Guests only: logged-in users are redirected to `AUTH_HOME_URL` |
| `a.TokenMiddleware` | Logs in the user of a `Bearer` API token; invalid tokens get 401; no token (or another scheme) passes as a guest |
| `a.RequireConfirmed` | Users who confirmed their password in the last `AUTH_CONFIRM_TTL` only: others are sent to `AUTH_CONFIRM_URL`, to come back after (to the page for GET, else to the page the form was on); API clients and htmx requests get `auth.ErrPasswordNotConfirmed` (423). After `Require` |

## Logging in and out

| API | Does |
|---|---|
| `a.Attempt(ctx, login, password, remember)` | Checks the password and logs in; `auth.ErrInvalidCredentials` (401), `*auth.ThrottledError` (429) past `AUTH_THROTTLE` attempts a minute per login or account and IP, or `AUTH_THROTTLE_IP` failures per IP; for a user with two-factor authentication on, the user and `auth.ErrTwoFactorRequired` (401): the login waits for a code |
| `a.Login(ctx, u, remember)` | Logs `u` in: new session ID; with `remember`, the remember-me cookie. For a user with two-factor authentication on, `auth.ErrTwoFactorRequired` instead, and a login waiting for a code (10 minutes). For logging in after registration and by other means than a password (it used to skip the code; `SignIn`, which asked for it, is deprecated) |
| `a.RememberCookie()` | The remember-me cookie's name (`__Host-anetos_remember`, `anetos_remember` with `WithInsecureCookies`) |
| `a.LoginSession(s, u)` | Writes a logged-in session for `u` into the `*session.Session` without a request, as `Login` without remember-me would, without asking for a two-factor code: for tests (`anetostest.ActingAs`) and tools; `auth.ErrDisabled` for a disabled user |
| `a.AttemptTwoFactor(ctx, code)` | Finishes the waiting login with the authenticator app's code (each used once) or a recovery code (used up); `auth.ErrInvalidCode` (422), `auth.ErrNoPendingLogin` (401: none, expired, or the password changed), `*auth.ThrottledError` past `AUTH_THROTTLE` a minute or 50 wrong codes a day (UTC) for the user; `auth.ErrDisabled` |
| `a.TwoFactorPending(ctx)` | Whether a login waits for a code in the session |
| `a.AttemptCredentials(ctx, login, password)` | `Attempt`'s check (its errors, throttling and rehashing) without a session: returns the user, for an API's login to give a token; `auth.ErrDisabled` (403); for a user with two-factor authentication on, a `*auth.TwoFactorChallenge` (401, `errors.Is` `auth.ErrTwoFactorRequired`) whose `Token` the client sends back with a code. The route needs `TokenMiddleware` or `Middleware` |
| `a.AttemptTwoFactorChallenge(ctx, challenge, code)` | Finishes such a login: checks the challenge (10 minutes, until the password or session key changes) and the code as `AttemptTwoFactor` does (its lock, limits and errors; `auth.ErrNoPendingLogin` for a bad, expired or outdated challenge) and returns the user; no session. A challenge works again within its 10 minutes, with a new code |
| `a.CheckPassword(ctx, u, password)` | Checks `u`'s password with `ConfirmPassword`'s budget (`AUTH_THROTTLE` a minute, 50 wrong a day), without a session: for an API, before what pages put behind `RequireConfirmed`; `auth.ErrInvalidCredentials`, `*auth.ThrottledError` |
| `a.ConfirmPassword(ctx, password)`, `a.PasswordConfirmed(ctx)` | Checks the logged-in user's password again, which holds for `AUTH_CONFIRM_TTL`; `auth.ErrInvalidCredentials` (also without a password); `AUTH_THROTTLE` tries a minute for the user, from any address, and 50 wrong passwords a day (UTC, shared with `ChangePassword`); not while impersonating another user. For a user without a password, a login through `Login` counts. Logging in or out, and impersonating someone, forget it; never for API tokens |
| `a.SupportsRemember()` | Whether "remember me" is available (`Users.RememberToken` set) |
| `a.Logout(ctx)` | Empties the session, removes the cookie, replaces the remember token |
| `auth.User[U](ctx)` | The logged-in user, and whether there is one |
| `auth.Current[U](ctx)` | The logged-in user, `auth.ErrUnauthenticated`, or the load error |
| `auth.Check(ctx)` | Whether a user is logged in |
| `auth.CurrentID(ctx)` | The logged-in user's `AuthID`, `auth.ErrUnauthenticated`, or the load error, for code that works with any user type |
| `a.WithUser(ctx, userID, opts...)`, `auth.WithUser(ctx, userID, opts...)` | A context whose logged-in user is that user (loaded with `Users.ByID` when asked for; none if it doesn't exist), for queue jobs and commands working for a user; no session (`Attempt`, `Login` and `Logout` refuse) and no token, unless `auth.WithAbilities(abilities)` gives it a token's limits. The function finds the app's Auth in ctx |
| `auth.Intended(ctx, fallback)` | The page a guest asked for before logging in, or `fallback` |

## Accounts

| API | Does |
|---|---|
| `Users.Disabled`, `a.Disabled(u)` | A disabled user is logged out on their next request; `Attempt` (once the password checks out) and `Login` return `auth.ErrDisabled` (403); their remember-me cookies and API tokens stop working; `WithUser` treats them as a guest |
| `a.ChangePassword(ctx, u, current, new)` | Changes `u`'s password (needs `Users.SetPassword`), logging them out of their other sessions and remember-me cookies (`LogoutOthers`); `auth.ErrInvalidCredentials` for a wrong `current`; a user without a password sets one without `current` within `AUTH_CONFIRM_TTL` of logging in (`auth.ErrPasswordNotConfirmed` after); `AUTH_THROTTLE` tries a minute, and 50 wrong passwords a day (UTC, shared with `ConfirmPassword`); not while impersonating someone |
| `a.LogoutOthers(ctx, u)` | Ends `u`'s other sessions (with `Users.SessionKey`), remember-me cookies and password-reset links, keeping the request's session if it is `u`'s (with a new session ID, and a new remember-me cookie if it had one) |
| `a.LogoutEverywhere(ctx, u)`, `a.SupportsLogoutEverywhere()` | Ends every session and remember-me cookie of `u` by giving them a new session key (`Users.SetSessionKey`) and remember token; API tokens stay |
| `a.Impersonate(ctx, u)` | Logs the current user in as `u`, keeping who they are in the session; not through API tokens, not nested, not for a disabled `u` (`ErrDisabled`) or oneself. Each request checks that the impersonator may still log in; `Logout` ends both (leaving `u`'s remember-me token alone). The impersonator's remember-me cookie is removed. Check who may first (`rbac.AuthorizeOver`) |
| `a.StopImpersonating(ctx)` | Logs the impersonator back in and returns them; `auth.ErrNotImpersonating` (409) without impersonation; if they can't log in any more, logs out and returns why |
| `auth.Impersonator(ctx)` | The ID of the user impersonating the logged-in one, and whether there is one |

## Two-factor authentication

TOTP (RFC 6238: six digits, 30 seconds, HMAC-SHA-1) and recovery codes;
see [Two-factor authentication](https://docs.anetos.dev/guides/two-factor/index.md). Needs
`Users.TwoFactor` and `SetTwoFactor`.

| API | Does |
|---|---|
| `a.SupportsTwoFactor()` | Whether two-factor authentication is available |
| `a.TwoFactor(u)` | `auth.TwoFactorStatus{On, Started, RecoveryCodes}`; an error if the state can't be read (`APP_KEY` changed) |
| `a.StartTwoFactor(ctx, u, account)` | Stores a new secret, replacing a started setup; returns `auth.TwoFactorSetup{Secret, URI}` (base32 key, `otpauth://` URI with `APP_NAME` as issuer); `auth.ErrTwoFactorOn` (409) if on |
| `a.StartedTwoFactor(u, account)` | The started setup again; `auth.ErrTwoFactorOff` if none, `ErrTwoFactorOn` once on |
| `a.ConfirmTwoFactor(ctx, u, code)` | Turns it on with a current code; returns 8 recovery codes (`abcde-fghij`), to show once; ends `u`'s other sessions and remember-me cookies (`LogoutOthers`); `auth.ErrInvalidCode`, `ErrTwoFactorOff`, `ErrTwoFactorOn`; throttled |
| `a.NewRecoveryCodes(ctx, u)` | Replaces the recovery codes; `auth.ErrTwoFactorOff` if off |
| `a.DisableTwoFactor(ctx, u)` | Turns it off (or drops a started setup) |
| `auth.TwoFactorCode(secret, t)` | The code an app shows at `t`, for tests |

## Tokens

| API | Does |
|---|---|
| `a.PasswordResetToken(u)`, `a.CheckPasswordResetToken(ctx, token)` | Reset tokens: `AUTH_RESET_TTL`, until the password or the session key changes; `auth.ErrInvalidToken` (400) |
| `a.VerificationToken(u, email)`, `a.CheckVerificationToken(ctx, token)` | Email-verification tokens: `AUTH_VERIFY_TTL`; returns the user and the address |
| `a.EmailRevertToken(u, old, new)`, `a.CheckEmailRevertToken(ctx, token)` | Tokens for the link, sent to the old address, that undoes a change of email address: `AUTH_REVERT_TTL`; returns the user and both addresses |
| `a.CreateToken(ctx, u, name, abilities, ttl)` | An API token (`<id>\|<secret>`, shown once) and its stored `auth.Token`; 403 while impersonating another user. Put the route behind `RequireConfirmed` |
| `a.Tokens(ctx, u)`, `a.RevokeToken(ctx, u, id)`, `a.RevokeAllTokens(ctx, u)` | A user's API tokens; delete one, or all |
| `a.RevokeOtherTokens(ctx, u, keep)` | Deletes `u`'s API tokens but `keep` (the request's, after a password change through the API) |
| `a.ClientLink(path, query)` | `AUTH_CLIENT_URL` joined with `path` and `query`: the link an API's emails give to the client app; an error naming the setting when it isn't set |
| `auth.CurrentToken(ctx)`, `auth.TokenCan(ctx, ability)` | The request's API token; whether it (or a session user) may do `ability` (`"*"`: all) |
| `auth.RequireAbilities(abilities...)` | Middleware: a token needs every one of the abilities (403 without them, 401 for a guest); a session user may do anything. Its routes' OpenAPI security lists them as scopes |

## Authorization

| API | Does |
|---|---|
| `auth.Authorize(ctx, policy, subject)` | nil, `auth.ErrUnauthenticated` (401) or `auth.ErrForbidden` (403); `policy` is `func(context.Context, U, T) bool` |
| `auth.AuthorizeUser(ctx, policy)` | The same for `func(context.Context, U) bool` |
| `auth.Allows`, `auth.AllowsUser` | The answer as a boolean (false for a guest) |
| `auth.IsDenied(err)` | Whether `err` is `ErrUnauthenticated` or `ErrForbidden` |

## Passwords

| API | Does |
|---|---|
| `password.Hash(pw)` | argon2id hash (19 MiB, 2 passes, 1 thread), as a PHC string; `password.ErrTooLong` over 1024 bytes |
| `password.Verify(pw, hash)` | Checks against argon2id or bcrypt (`$2a$`, `$2b$`, `$2y$`) hashes |
| `password.NeedsRehash(hash)` | bcrypt, or argon2id weaker than the defaults |
| `password.HashWith(pw, params)`, `password.Defaults()` | Other parameters (at most 256 MiB and 10 passes) |
| `password.IsBcrypt(hash)` | Whether the hash is bcrypt, which checks only a password's first 72 bytes |
| `password.Dummy(pw)` | Spends the time of a check, for unknown users |
| `password.VerifyContext(ctx, pw, hash)`, `password.DummyContext(ctx, pw)` | The same, giving up with ctx's error while waiting for a free slot (a few hashes are computed at once) |

## Social login

| API | Does |
|---|---|
| `social.Google()`, `social.GitHub()`, `social.GitHubAt(web, api)`, `social.OIDC(name, issuer)` | Providers; their `Scopes`, `Title` ("Google", for buttons; `OIDC`'s defaults to its name) and other fields can be changed |
| `social.Configured(app, providers...)` | The providers whose `SOCIAL_<NAME>_CLIENT_ID` and `_CLIENT_SECRET` are set |
| `social.New(app, a, resolve, providers, opts...)` | `*social.Social[U]`; needs `APP_URL` (https in production); with no providers, its routes answer 404; `social.WithHTTPClient`, `social.WithLogger`, `social.WithCallbackPath`, `social.WithHomeURL(path)` (where users go without an intended page; default `AUTH_HOME_URL`) |
| `social.NewWithConfig(a, resolve, baseURL, creds, providers, opts...)` | Without an app |
| `s.Redirect`, `s.Callback` | Handlers for `/auth/{provider}/redirect` (`?remember=1`) and `/auth/{provider}/callback` |
| `s.Providers()`, `s.CallbackURL(name)` | Provider names, in the order given; a provider's callback URL to register |
| `social.Resolver[U]`, `social.Profile` | `func(ctx, Profile) (U, error)`: finds or creates the user; the profile has `Provider`, `Subject`, `Email`, `EmailVerified`, `Name`, `AvatarURL`, `Token` |
| `social.NoAccountError{Message}` | Refuses a login with a message on the login page (`social` field) |
| `s.Providers()`, `s.Title(name)` | The providers' names, in the order given, and their titles, for login buttons |
| `social.Migrations()` | The `social_accounts` table |
| `social.FindLink(ctx, p)`, `social.Link(ctx, p, userID)`, `social.Links(ctx, userID)`, `social.Unlink(ctx, userID, provider)` | Links between provider accounts and users |

## Roles and permissions

Package `auth/rbac`. Concepts: [Roles and permissions](https://docs.anetos.dev/concepts/roles-and-permissions/index.md).

### Declaring

| API | Does |
|---|---|
| `rbac.Permission` | A string type: `const EditPosts rbac.Permission = "posts.edit"`; lowercase letters, digits and `. _ : -`, up to 100 characters; also the API token ability that allows it |
| `rbac.Role{Name, Title, Permissions, Super, Custom}` | A role; `Super` has every permission (code only); `Custom` is set for roles of the database. `r.Allows(p)`, `r.DisplayName()` (the title, or the name) |
| `rbac.New(app, permissions, roles...)` | `*rbac.Registry`, checked (unique names, roles of declared permissions); provided to the app and its contexts; caches grants per operation; adds the commands below; once per app |
| `rbac.NewRegistry(permissions, roles...)`, `rbac.WithRegistry(ctx, reg)`, `rbac.From(ctx)` | Without an app; `rbac.ErrNoRegistry` when the context has none |
| `reg.Declare(permissions...)` | Adds permissions to the registry, for packages that bring their own (the admin); idempotent; call it at setup, before the app serves |
| `rbac.AuthorizeOver(ctx, userID)` | nil if the logged-in user has every permission `userID` has in every scope (and a super role wherever they have one), else `auth.ErrForbidden`: for managing their account |
| `rbac.GivenTo(ctx, userID)` | The roles and permissions given to a user, as stored (`rbac.Given{Scope, Role, Permission}`), by scope and name |
| `rbac.RoleCounts(ctx)`, `rbac.Holders(ctx, role, limit)` | How many users have each role; who has a role, and where (`rbac.Holder{UserID, Scope}`) |
| `reg.Permissions()`, `reg.Declared(p)`, `reg.Roles()`, `reg.Role(name)` | What was declared |
| `rbac.Migrations()` | The `rbac_grants` and `rbac_roles` tables |

### Scopes

| API | Does |
|---|---|
| `rbac.Scope`, `rbac.Global` | Where a grant applies: `rbac.Global` (`""`) everywhere, or one scope |
| `rbac.ScopeOf(kind, id)` | `"team:42"`; `kind` is lowercase letters, digits, `_` and `-` (panics otherwise); IDs compare exactly (`ABC` isn't `abc`, on every database); stored scopes are up to 100 bytes (`rbac.ErrInvalidScope`, 422) |
| `s.Kind()`, `s.ID()`, `s.String()` | `"team"`, `"42"`; `"global"` for `rbac.Global` |

### Checking the logged-in user

A global grant applies in every scope. For a request logged in with an
API token, a permission must also be among the token's abilities (or
the token has `*`), and role checks are false unless it has `*`.

| API | Does |
|---|---|
| `rbac.Authorize(ctx, p)`, `rbac.AuthorizeIn(ctx, scope, p)` | nil, `auth.ErrUnauthenticated` (401), `auth.ErrForbidden` (403), or another error (the database; an undeclared permission, 500) |
| `rbac.Can(ctx, p)`, `rbac.CanIn(ctx, scope, p)` | The answer as a boolean: false for a guest; other errors are logged |
| `rbac.HasRole(ctx, role)`, `rbac.HasRoleIn(ctx, scope, role)` | Whether the user has the role in scope or globally |
| `rbac.AuthorizeRole(ctx, scope, role)` | nil if the user may give the role in scope: they have every permission it allows there (super there, with a `*` token, for a super role); else 401, 403 or `rbac.ErrUnknownRole`. Compares permissions, not names |
| `rbac.AuthorizeRolesOf(ctx, scope, userID)` | nil if the user may give every role `userID` has in exactly `scope`, so may change or remove them; else 401 or 403 |
| `rbac.Require(perms...)`, `rbac.RequireIn(scopeFn, perms...)` | Middleware: every permission, globally or in `scopeFn(r)`'s scope; the error of `Authorize` otherwise. After the auth middleware |
| `rbac.PathScope(kind, param)` | A `scopeFn` from a path parameter: `PathScope("team", "team")` on `/teams/{team}`; 404 without it |
| `rbac.Current(ctx)` | The logged-in user's `*rbac.Grants` (token limits applied), or `auth.ErrUnauthenticated` |

### Any user's grants

| API | Does |
|---|---|
| `rbac.Of(ctx, userID)` | The user's `*rbac.Grants`, read in one query (two with roles of the database) once per operation (request, job, listener, task, tool call) |
| `g.Can(p)`, `g.CanIn(scope, p)` | Whether a grant in scope, or a global one, allows `p` |
| `g.HasRole(role)`, `g.HasRoleIn(scope, role)` | Whether the user has the role in scope or globally (declared or stored roles only; none for a token without `*`) |
| `g.Roles(scope)` | The roles assigned in exactly `scope`, by name (the same rules) |
| `g.Permissions(scope)` | The permissions allowed in `scope` (with global grants), in declaration order |
| `g.Scopes(kind)` | The scopes of `kind` where the user has a role or a declared permission, sorted: their teams |

### Changing grants

| API | Does |
|---|---|
| `rbac.Assign(ctx, userID, scope, roles...)` | Adds roles (declared, or of the database: `rbac.ErrUnknownRole`, 422); user IDs are up to 100 bytes |
| `rbac.Unassign(ctx, userID, scope, roles...)` | Takes roles away in exactly `scope` |
| `rbac.Sync(ctx, userID, scope, roles...)` | Makes `roles` the user's only roles in `scope` (none: removes them all) |
| `rbac.Grant(ctx, userID, scope, perms...)`, `rbac.Revoke(…)` | Single permissions without a role (`rbac.ErrUnknownPermission`, 422) |
| `rbac.RemoveUser(ctx, userID)` | Every grant of the user, in every scope |
| `rbac.RemoveScope(ctx, scope)` | Every grant in the scope (not `rbac.Global`) |
| `rbac.Assignments(ctx, scope)` | `[]rbac.Assignment{UserID, Role}` in exactly `scope`, by user and role: its members |
| `rbac.UsersWith(ctx, scope, p)` | IDs of the users allowed `p` in `scope` (with global grants), sorted |

### Roles of the database

| API | Does |
|---|---|
| `rbac.CreateRole(ctx, role)` | Stores a role of declared permissions; `rbac.ErrRoleExists` (409), `rbac.ErrInvalidRole` (422: invalid name or title, a code role's name, super); users still holding a removed code role of the name lose it |
| `rbac.UpdateRole(ctx, role)` | Replaces its title and permissions; `rbac.ErrUnknownRole`, `rbac.ErrInvalidRole` for a code role |
| `rbac.DeleteRole(ctx, name)` | Deletes it and its assignments |
| `rbac.Roles(ctx)`, `rbac.FindRole(ctx, name)` | Every role, code's first; one role, code's or the database's |

### Commands

| Command | Does |
|---|---|
| `rbac:roles` | The roles, where they're defined, their users and permissions; warns of assigned roles that are neither declared nor stored, and of stored roles a code role replaces |
| `rbac:user <user-id>` | A user's roles and permissions by scope |
| `rbac:assign [--scope=team:42] <user-id> <role>` | Gives a role, globally without `--scope` |
| `rbac:unassign [--scope=team:42] <user-id> <role>` | Takes it away |
