Accounts ¶

Optional PostgreSQL accounts using installable app API 1. This source module uses replace github.com/fauzaanu/cicadel => ../.. for repository development; no remote module release is claimed.

In a generated application’s project.InstalledApps(db), construct accounts.New(accounts.Options{DB: db, DeliverRecovery: deliver}), handle its error, and append service.HTTPApp("/accounts"). Run manage.go migrate before serving. The migration is recorded SQL, never AutoMigrate. Removing registration preserves data. The host owns its database pool.

The HTTP endpoints accept POST JSON with Content-Type: application/json:

Clients send Authorization: Bearer <token>. These routes use no ambient cookies. Install service.Middleware explicitly on host routes requiring current-user context; use UserFromContext and reject anonymous requests where needed. The middleware does not itself require authentication. For browser applications, construct service.Browser(sessions) and wrap routes with browser.Middleware. This composes SCS LoadAndSave, CSRF validation and account resolution in order. Use browser.Login, browser.Logout, browser.CSRFToken and browser.RequireLogin in HTML handlers. The account token is held only in the server-side session; disablement and revocation are checked on every request. Do not additionally wrap these routes with SCS/CSRF middleware. SCS login alone does not create an accounts session. Existing SCS APIs remain compatible. This package does not change forms, uploads or admin.

Tokens contain cryptographic randomness and only SHA-256 digests are stored. Password changes and recovery revoke all sessions and recovery tokens in one transaction. Recovery consumption locks the user and rechecks token deletion, so concurrent redemption succeeds once. Session creation serializes with password changes. SetActive(false) revokes sessions and recovery tokens. Disabled users cannot log in, resolve current-user context or use permissions.

Passwords must contain 12–72 bytes. Policy adds application validation; bcrypt cost defaults to 12 (configurable 10–16). Successful password authentication upgrades lower costs without downgrading stronger hashes or overwriting a concurrent password change. Backend can verify another credential source but must return an existing local account; central disabled-user checks still apply.

SessionLifetime defaults to 24 hours and RecoveryLifetime to 30 minutes; both are absolute lifetimes of at least one minute. Optional IdleTimeout expires sessions after inactivity; successful current-user resolution refreshes activity. PostgreSQL is the persistent store. Schedule manage.go accounts:cleanup to remove expired sessions/recovery records. No background worker is started. Transport security, request rate limits, and recovery delivery belong to the host. Delivery must send the raw token only to the account’s previously verified recovery destination; never to an arbitrary request-supplied address. Avoid logging tokens or credentials.

Groups use CreateGroup, AddMember, RemoveMember, Grant, and Deny. HasPermission checks exact application-defined model/action strings such as posts.change. There is no superuser bypass or implicit object access. Apply an explicit host policy for each object in addition to model permissions.

OAuth/OIDC, social login and MFA remain outside scope. The accountui package supplies compiled HTML account screens. Administration integration remains separate.

Run CICADEL_TEST_DATABASE_URL=postgres://...?... go test -race ./... with a disposable PostgreSQL database and schema creation privileges. Tests isolate and remove their schema. Parent module tests do not include this nested module.

sh contrib/accounts/verify-host.sh generates a separate application, registers the package via local module replacements, applies its public migration contract, and verifies login/logout over HTTP. Use a disposable database; the verification applies accounts migrations and removes its test user afterward.

Browser pages ¶

Use service.Browser(sessions) and browser.HTMLApp(Pages{Brand: "My app"}) for the default compiled HTML screens. Register that app once and migrate before serving. It owns its cookie/CSRF middleware and embedded CSS; other protected routes apply browser.Middleware followed by browser.RequireLogin. UserFromContext is shared with the bearer adapter. The browser stores the account token only in the server-side SCS store, rotates login cookies and checks revocation/disablement on every request.

Migration 002 adds the PostgreSQL accounts_browser_sessions table used by the starter. Custom session stores remain supported. Use cicadel startproject DIRECTORY MODULE for a wired project, including verified account provisioning and SMTP recovery delivery. Read the complete authentication guide for the route table, configuration, middleware ownership and testing. There is no public signup or administrator panel in this starter.

This module owns .templ source and generated Go/CSS. Run ui build and ui check --json using the matching framework CLI, in addition to its tests.