golem15.user

The shared front-end user plugin for SummerCMS applications: registration, login with JWT sessions, activation and password reset, profile and avatar endpoints.

import _ "git.golem15.com/golem15/sm-user-plugin"

Module git.golem15.com/golem15/sm-user-plugin, package user, plugin ID golem15.user.

Overview

The plugin is a compiled SummerCMS plugin. Its init registers it with the framework, so an application loads it by listing it in summer.yaml; summer build then emits the blank import above into the application's plugins.gen.go.

It owns the users table extensions, user_throttle, jwt_blacklist, user_api_tokens, golem15_user_oauth_identities, golem15_user_organisations, user_groups, users_groups and golem15_user_frontend_permissions, the JSON API under /_user/api/v1, and the Users, User Groups and Organisations screens of the admin. It is a core plugin shared by several applications, so its routes, payloads, table names, migration IDs, permission codes and config keys are a contract: change them only in a backwards-compatible way.

Features

• Registration and activation. POST /register, POST /activate, POST /activate-by-code. Registration can be switched off and throttled; activate_mode is auto, user (a mailed code) or admin, with codes from IssueActivationCode and VerifyActivationCode. A /register body sets only the User.RegisterFillable columns: name, surname, email, password (stored as its hash), preferred_locale and marketing_consent. It cannot set organisation_id or organisation_role (membership is the administrator's or the application's), is_onboarded, must_change_password, or the activation, reset, address proof, handle and permission columns; other keys are ignored (they still reach RegisterEvent.Payload). created_ip_address and last_ip_address are server-set from the client address only. With require_activation on (the default), POST /login refuses an account that is not activated with the same 401 invalid-login answer as a wrong password and counts the attempt for the login throttle. Such an account is activated by the mailed code (POST /activate-by-code answers with a token), by the invitation link or by an administrator. POST /activate serves the sessions of not-activated accounts, which exist when require_activation is off. Login checks in this order: a ban or an active suspension (RejectIfThrottled), the password, the activation, then the deactivation restore.
• JWT sessions. POST /login, GET /fetch, POST /refresh, POST /logout. Boot registers the jwt guard with the framework's bouncer.Registry and exposes it as the jwt.auth middleware for other plugins. The guard reads the session cookies classes.SessionCookieNames() lists and resolves the published bouncer.BlacklistStore on every request. Boot installs the plugin's GORM hooks (classes.RegisterHooks), publishes the Postgres jwt_blacklist store (bouncer.NewPostgresBlacklist) and starts its background sweep, which prunes the blacklist, through lagoon.OnDatabase. Under summer serve, which publishes the database after Boot, they take effect when lagoon.Publish runs, before the router is built; when the database is already published they take effect at once. While no store is published, no token counts as blacklisted. POST /logout ends the session however the token travels: the bearer header, or only the token or auth_token cookie the guard also reads. Every session token the request carries goes to the Postgres jwt_blacklist until its refresh window closes (the later of exp and iat plus refresh_ttl, plus a minute), so the guard refuses it on the next request and POST /refresh cannot revive it after the access token expired; a token whose access lifetime passed is revoked too while it could still be refreshed. The answer, a 401 included, expires the auth.cookie.* token cookie (the one golem15.sociallogin's token_cookie sets), and any other session cookie the request carries, with that cookie's path, domain, SameSite and Secure. POST /refresh loads the token's user and refuses (401, Could not refresh token, User not found) a deactivated or banned user and a token issued before the user's tokens_valid_after; a suspension alone does not stop a refresh. GET /fetch, POST /refresh, POST /update and POST /change-password, like the plugin's other signed-in routes, read the session token as the jwt guard does: the bearer header first, then the token and auth_token cookies, so a cookie-only session works on them and a bearer header wins when both are sent. A POST /refresh whose token came from the auth.cookie.* cookie (auth.cookie.name, default token) with no bearer header gets that cookie back with the rotated token: the cookie has the bouncer.LoadCookieConfig attributes, HttpOnly and Max-Age refresh_ttl, and the answer is {}, so the token never reaches JavaScript. This holds whoever wrote the cookie (this plugin's golem15.user.jwt.token_cookie, golem15.sociallogin's token_cookie or the application); a frontend that writes the token cookie itself and refreshes through it gets it back HttpOnly, without a body token, so such a frontend sends the bearer header to keep rotating in the body. A refresh carried by the bearer header (a cookie sent with it included) or by the other session cookie answers {"token": …} and writes no cookie; the old token is blacklisted after golem15.user.jwt.blacklist_grace, so that caller stores the new token itself. A refused refresh writes and forgets no cookie. When bouncer.LoadCookieConfig refuses the auth.cookie block, a cookie-carried refresh answers the opaque 500 before anything is rotated; a bearer refresh never reads that block. Keep auth.cookie.name at token or auth_token, the cookies the guard reads. With golem15.user.jwt.token_cookie on, POST /login, POST /register (when it signs the new account in) and POST /activate-by-code set that HttpOnly session cookie (bouncer.LoadCookieConfig attributes, Max-Age refresh_ttl) and leave token out of the body; user, and message on activate-by-code, stay. With it off (the default) the token is in the body and no cookie is set. SameSite stays the auth.cookie setting (lax by default) and there is no CSRF token, so do not set same_site: none for this cookie. With the key on, a broken auth.cookie block answers those three routes with the opaque 500 before they sign in, create or activate anything. Personal API tokens (POST /tokens) are not sessions and are unaffected. A cookie-carried session relies on the cookie's SameSite attribute against cross-site requests (the auth.cookie default is lax), as on the jwt.auth routes.
• Password reset and change. POST /forgot-password answers the same body for known and unknown addresses; POST /reset-password consumes a code from IssueResetCode. POST /change-password requires the current password. With golem15.user.password.public_routes false, POST /login, POST /forgot-password and POST /reset-password are not registered, so they answer the router's own 404 like any unknown path (any method, so no 405 shows they exist), while the controllers handlers stay exported.
• Must-change-password lock. The user:require-password-change console command flags an account. The flag rides on the authenticated principal (bouncer.Principal.MustChangePassword) for guards and other plugins to act on, and a successful POST /change-password clears it.
• Login throttling. Failed logins are counted per user and client address in user_throttle (CheckAndRecordLogin, RejectIfThrottled) and suspend the account for a configured time. The client address is surf.ClientIP with the framework's http.trusted_proxies, as for the /register IP limit and the user-api rate limit: behind a listed reverse proxy it is the X-Forwarded-For client, otherwise the connection address, and an X-Forwarded-For header from any other peer is ignored. A deployment behind a proxy lists the proxy's address in http.trusted_proxies; otherwise every visitor shares the proxy's counter.
• Rate limiting. Every route runs behind the user-api bucket: 120 requests a minute per authenticated user, or per client IP for anonymous calls.
• Profile. POST /update, POST /marketing-consent, POST /avatar and POST /avatar/remove (the avatar is stored through the framework's attachment storage).
• Deactivation and bans. Deactivation is self-service and reversible: a password login or a golem15.sociallogin sign-in restores a deactivated account and sends the reactivate mail, and an administrator can restore it too. It ends every earlier session JWT and personal API token of the user (RevokeUserAccess stamps tokens_valid_after and revokes the user_api_tokens rows), so the user signs in again and gets a fresh token, while the old API tokens stay revoked. A ban is the lock: password login, social sign-in and POST /refresh refuse a banned user, and banning revokes the user's sessions and API tokens. Neither unban nor restore revives a token. Activation gates login, deactivation does not: while require_activation is on, an account that is both deactivated and not activated is refused and stays deactivated, with no reactivate mail. Upgrade note: accounts deactivated or banned before this version keep their API tokens until they are deactivated or banned again (both actions are idempotent) or RevokeUserAccess runs for them.
• Organisations. The Organisation model and the organisation_id and organisation_role user columns, as a foreign-key target for other plugins. An organisation has a name, a slug (filled from the name by Slugify when it is left empty), a description, an avatar and its members: the users whose organisation_id points at it. organisation_role belongs to that membership: the admin clears it whenever a user's organisation changes (see the Organisations screen), and an application that sets organisation_id itself sets or clears the role with it.
• User groups. The user_groups table (seeded with the guest and registered groups, as in PHP) and the users_groups membership pivot, the UserGroup model and the User.Groups relation, which is never serialized. UserGroupCodes and HasGroupCode let other plugins check membership server-side, for example a site-admin check on the group code admin. No user API route reads or writes groups, and the user payload still answers "groups":[]. Membership is written in one place only: the groups field of the admin user form. Apart from that, rows leave users_groups only when a user or a group is deleted for good. The admin Users list can filter by group.
• Admin screens. The plugin registers the Users screen with the framework's admin (pact.HasAdminControllers, controller ID golem15.user.users), the port of the WinterCMS Users controller: a list with search, the group, registration date and activated filters and row states (deactivated, banned, not activated); a read-only preview with a status hint; and a form with name, email, a password with confirmation, an optional invitation mail, the user's groups, the organisation, the avatar and the user's frontend permissions. Bulk actions activate, deactivate, restore, ban and unban users; the preview offers activate, unban and unsuspend while they apply. Deactivating is the soft delete, and deactivate and ban both end the user's earlier sessions and personal API tokens (see Deactivation and bans); the delete button and the bulk delete remove a user for good, together with the throttle rows, group memberships and attachments. A user created in the admin starts not activated. There is no impersonation and no guest account.
• User Groups screen. Controller ID golem15.user.usergroups, the port of the WinterCMS UserGroups controller, behind golem15.users.access_groups: a list with the name, code, creation date and number of members, and a form with the name, the code (letters, digits, underscore and hyphen; unique), a description and the group's frontend permissions as checkboxes, stored in user_groups.permissions as a JSON object of code to 1. A group can be deleted from its form; its memberships go with it and its members stay. The screen never changes who is in a group.
• Organisations screen. Controller ID golem15.user.organisations, the port of the WinterCMS Organisations controller, behind golem15.users.access_users: a list and a form with the name, slug, description and avatar, and on an existing organisation the Members tab. Adding a member sets that user's organisation_id and removing one clears it; both also clear the user's organisation_role, so a role never moves to another organisation or outlives the membership. A user is never deleted. Only users without an organisation can be added, so a user moves by being removed from one organisation and added to the other (or through the organisation field of the user form, where a save that changes the organisation, to another one or to none, clears organisation_role unless the same save writes it). Deleting an organisation clears organisation_id and organisation_role of its members first.
• Privileged groups. The groups whose code is listed in golem15.user.privileged_groups (default admin) are privileged: an application may treat their members as site administrators. Three things therefore need the backend permission golem15.users.manage_privileged_groups on top of the screen's own permission, and answer 403 without it, saving nothing. First, membership: adding a privileged group to a user or removing it, on create and on update of the user form. An administrator without the permission sees those groups locked in the field and can still change the user's other groups. Second, the code: creating a group with a privileged code, changing a group's code to or from a privileged one, and deleting a privileged group. Its name, description and frontend permissions need only golem15.users.access_groups. Codes compare case-sensitively, and a group without a code is never privileged. Third, the member's account, which is protected against takeover: changing that user's email or password, and deleting them for good, needs the backend permission golem15.users.manage_privileged_groups on top of golem15.users.access_users. Without it the request answers 403 and nothing is saved; a bulk delete that contains such a user deletes none of the selected users. Everything else on such a user (name, organisation, avatar, frontend permissions, activate, deactivate, restore, ban, unban, unsuspend) needs only golem15.users.access_users. PrivilegedGroupCodes, IsPrivilegedCode, PrivilegedGroupIDs and IsPrivilegedMember expose the rule to other code.
• Frontend permissions. golem15_user_frontend_permissions is the catalogue of permissions a site defines for its users (rows come from the application's migrations or seeds). A user's own choices are stored in users.permissions and a group's in user_groups.permissions, as a JSON object of code to 1 (allow) or -1 (deny). MergedPermissions combines them as PHP getMergedPermissions does: among a user's groups the most positive value wins, then the user's own value replaces the groups'. HasPermission and UserHasPermission answer whether a code is held: only at exactly 1, with Winter's * wildcards. Neither value appears in the user payload, whose permissions key stays null.
• Last seen. users.last_seen is stamped by POST /login and a successful POST /refresh through TouchLastSeen, at most once per five minutes per user. A failed write is logged and never fails authentication. It is shown in the admin list and is not part of any user payload.
• Address proof. users.email_verified_at records when the account's owner proved control of the address (User.EmailVerifiedAt). Exactly two flows write it: the mailed activation code (POST /activate, POST /activate-by-code and the invitation link, through VerifyActivationCode) and a completed reset-code password reset (POST /reset-password). POST /register in auto or admin mode, RegisterUser, an administrator's create and the admin Activate action, POST /change-password and social sign-ins record none. The proof follows the address: an email change through POST /update or the admin Users form clears it, while a change of letter case only keeps it. The column is never mass-assigned and is in no user API payload, admin form or list. No migration or code path backfills it: accounts from before v0.1.5 have no proof. An application that trusts its imported addresses may set the column in its own data migration; this plugin does not. A social-login plugin links a verified provider's identity onto an existing account only when it is set.
• Handle. users.handle is a unique nullable VARCHAR(255) generated on create (classes.HandleGenerator, charset [a-z0-9._-], length 2–255). It is omitted from the user JSON payload (json:"-"). user:backfill-handles fills existing rows that still have none.
• User lighthouse authorizer. Boot calls classes.RegisterUserAuthorizer: lighthouse.From then Registry.Register("user", …) if the namespace is free. classes.AuthorizeUser allows only user:{id} for that user (lighthouse.ChannelID on the two-segment name).
• Shared API tokens. user_api_tokens stores one hashed personal/OAuth credential per user for the whole application. The user.api_token guard authenticates it for any plugin; user.scope:<scope> limits delegated access and user.permission:<code> checks the user's current group permissions. POST/GET/DELETE /tokens manage personal tokens, and user:token:create, user:token:list and user:token:revoke provide the CLI equivalent. A raw secret is shown only when created.
• Mail templates. Activation, reset, reactivation and invitation mails in Polish and English (golem15.user::mail.*, layout golem15.user::mail.layouts.user); the locale follows the user (ResolveMailLocale). The invitation (golem15.user::mail.invite) is sent when an administrator creates a user with "Send invitation by email" set; it carries the user's login and an activation link, never the password.
• Extension events. RegisterEvent fires after a user row is created; its Payload is a copy of the register input (extra keys a client sent included, password and password_confirmation never), so it is untrusted client input. CreatedEvent (classes.CreatedEventName user.Created) fires from API register and admin create. /register logs a failing RegisterEvent or CreatedEvent listener at Error level and continues: a committed registration is never undone or failed by a listener. DeletingEvent (classes.DeletingEventName user.Deleting) fires from FormAfterDelete before ForceDeleteCleanup / unscoped delete, inside the same transaction. GetApiArrayEvent lets other plugins merge keys into the user payload.
• Registration for other plugins. RegisterUser, FireRegisterEvent, IssueToken and APIArray are the steps POST /register runs, exported so another plugin (a first-run setup endpoint, for example) creates a user with the same validation, hashing, event, token and payload.
• OAuth providers. GET /oauth-providers lists the social sign-in providers a social-login plugin has enabled, read on every request from its published classes.OAuthProviderSource. Without one it answers the empty list, as before.
• Sign-in helpers for social login. RegisterOptions.PasswordLess, FinishLogin, RegistrationSettings, RegistrationsFromIP, RefreshTTL and RemoteIP let a social-login plugin create accounts and finish logins with the user plugin's own rules instead of copies.

Usage

Mount the plugin in an application as a git submodule at plugins/golem15/user:

git submodule add git@git.golem15.com:golem15/sm-user-plugin.git plugins/golem15/user

Add it to the application's go.work:

use (
	.
	./plugins/golem15/user
)

Require it in the application's go.mod with a local replace:

require git.golem15.com/golem15/sm-user-plugin v0.0.0

replace git.golem15.com/golem15/sm-user-plugin => ./plugins/golem15/user

List it in summer.yaml and run summer build:

module: git.golem15.com/golem15/acme
binary: acme
plugins:
  - id: golem15.user
    module: git.golem15.com/golem15/sm-user-plugin

The plugin's own go.mod replaces the framework with ../../../../summercms.go, so it expects the framework checkout next to the application checkout (<dir>/summercms.go and <dir>/acme/plugins/golem15/user).

Because the plugin registers an admin screen, an application that loads it mounts the framework's admin API and must set admin.jwt.secret (SUMMER_ADMIN__JWT__SECRET); start-up fails while it is empty. The admin screens need framework release v0.1.3 or later.

Another plugin that needs the signed-in user puts its routes behind jwt.auth. A machine API uses user.api_token, optionally followed by user.scope:read, user.scope:write, or user.permission:vendor.plugin.code. Both guards resolve the same user and current group permissions. Import git.golem15.com/golem15/sm-user-plugin/models, .../classes, or .../middleware for the shared types and helpers.

API reference

All routes are mounted under /_user/api/v1 with the throttle:user-api middleware.

Method and path	Handler
POST /login	controllers.Login
POST /logout	controllers.Logout
GET /fetch	controllers.Fetch
POST /refresh	controllers.Refresh
POST /register	controllers.Register
GET /oauth-providers	controllers.OAuthProviders
POST /forgot-password	controllers.ForgotPassword
POST /reset-password	controllers.ResetPassword
POST /activate	controllers.Activate
POST /activate-by-code	controllers.ActivateByCode
POST /update	controllers.Update
POST /change-password	controllers.ChangePassword
POST /marketing-consent	controllers.MarketingConsent
POST /avatar	controllers.UploadAvatar
POST /avatar/remove	controllers.RemoveAvatar
POST /tokens	controllers.APITokenStore (jwt.auth)
GET /tokens	controllers.APITokenIndex (jwt.auth)
DELETE /tokens/{id}	controllers.APITokenDestroy (jwt.auth)

/fetch, /refresh, /update, /change-password, /activate, /marketing-consent, /avatar, /avatar/remove and the jwt.auth routes read the session token from the bearer header, then the token and auth_token cookies.

With golem15.user.password.public_routes false the /login, /forgot-password and /reset-password rows are not registered.

Host-mounted OAuth identities

The host application mounts these constructors on a path it chooses. They are not registered under /_user/api/v1. OAuthIdentitiesOptions.WriteNotFound is the host's 404 writer so missing, foreign and unknown providers share one body. OAuthIdentitiesOptions.Providers is the unlink allow-list; when empty it is read on every request from a published classes.OAuthProviderSource (its KnownOAuthProviders), else it is google, facebook, github and microsoft. Unlinking follows the PHP rule: it succeeds when the user has a self-set password (has_self_set_password) or another identity remains, and otherwise answers 409 with the phrase golem15.user::lang.oauth.last_method_blocked (body unchanged). The guarded delete runs in a transaction that first locks the user's users row, so two concurrent unlinks never remove the last sign-in method.

Constructor	Role
controllers.OAuthIdentitiesIndex	Lists the caller's linked providers as {provider, linked_at} only.
controllers.OAuthIdentitiesDestroy	Unlinks one provider for the caller (204), or answers 409 when it is the last sign-in method of a user without a self-set password.
controllers.OAuthIdentitiesOptions	Host injects Providers and WriteNotFound.

Admin

The three screens are served by the framework's generic admin API under <admin prefix>/api/v1/golem15/user/users, .../usergroups and .../organisations; the plugin adds no admin route of its own.

Item	Value
Admin controllers	golem15.user.users, golem15.user.usergroups and golem15.user.organisations, from controllers.AdminControllers
Navigation	main item user (order 555) with the side items users, usergroups and organisations, each shown to an administrator who holds its permission
Relation manager	members on golem15.user.organisations (link and unlink)
Bulk actions (Users)	activate, deactivate, restore, ban, unban, and the built-in delete; deactivate and ban also revoke the selected users' sessions and personal API tokens
Record actions (Users)	activate, unban, unsuspend

Backend permissions, all on the tab golem15.user::lang.plugin.tab:

Code	Default role	Grants
golem15.users.access_users	developer	The Users screen and every action on it, including a user's membership of ordinary groups, and the Organisations screen with its members.
golem15.users.access_groups	developer	The User Groups screen.
golem15.users.access_settings	developer	Registered for roles that already name it; no screen uses it yet.
golem15.users.impersonate_user	developer	Registered for roles that already name it; impersonation is not available.
golem15.users.manage_privileged_groups	none	Adding a privileged group to a user or removing it; creating, re-coding or deleting a privileged group; changing the email or password of a privileged-group member, and deleting one for good. Only a superuser or a role that was granted it holds it.

Migrations added for the admin, all additive:

ID	Adds
202610040001_add_users_permissions	users.permissions (text, nullable)
202610040002_add_users_last_seen	users.last_seen (timestamp, nullable)
202610040003_create_frontend_permissions	the table golem15_user_frontend_permissions (code unique, label, tab, comment)

Migrations added for linked OAuth identities, all additive:

ID	Adds
202610050001_create_oauth_identities	the table golem15_user_oauth_identities (user_id cascade FK to users, unique (user_id, provider) and (provider, provider_id), jsonb profile_data)

Migrations added for @mention handles, all additive:

ID	Adds
202610160002_add_handle_to_users	users.handle (VARCHAR(255) NULL, unique index users_handle_unique, ADD COLUMN IF NOT EXISTS; rollback is a no-op)

Migrations added for address proof, all additive:

ID	Adds
202610210001_add_users_email_verified_at	users.email_verified_at (TIMESTAMPTZ NULL, ADD COLUMN IF NOT EXISTS, no backfill; rollback is a no-op)

Packages:

• controllers: the route handlers above, AdminControllers (the admin controller list), PermissionAccessUsers and PermissionAccessGroups, plus the registration steps POST /register runs, for other plugins:
  • RegisterUser(ctx, app, db, fields, RegisterOptions) validates fields against the user model's rules, hashes the password with golem15.user.password.bcrypt_cost and creates the user on db (which may be a transaction). It fills only the User.RegisterFillable columns and ignores every other key of fields: an organisation membership and role are set with an explicit update after creation, as an application's onboarding does. It returns the validation errors instead of writing a response and never modifies fields. RegisterOptions.Activate creates the account activated; RegisterOptions.IP records the client IP and is the only source of created_ip_address and last_ip_address (both stay NULL without it, whatever fields says); RegisterOptions.PasswordLess stores has_self_set_password=false for an account whose random password the user never knew (a social sign-in), while the zero value keeps true.
  • FireRegisterEvent(ctx, app, user, fields) fires RegisterEvent with Payload set to a copy of fields without password and password_confirmation, and returns the listeners' error (/register logs it and continues). Payload carries every extra key the client sent, so treat it as untrusted. Fire it after the user row is committed.
  • FireCreatedEvent(ctx, app, user) fires CreatedEvent (user.Created) and returns the listeners' error; /register logs it and continues.
  • FireDeletingEvent(ctx, app, user, tx) fires DeletingEvent (user.Deleting) inside the delete transaction.
  • FireDeactivatingEvent(ctx, app, user, tx) fires DeactivatingEvent (user.Deactivating) inside the deactivation transaction. The admin deactivate bulk action fires it after DeactivateUsers (so the user's sessions and API tokens are already revoked) for every selected user that was not deactivated yet; a listener error rolls the action back.
  • IssueToken(app, user, r) mints the session JWT as /register and /login do.
  • APIArray(ctx, app, user) builds the user payload, extended by GetApiArrayEvent listeners.
  • FinishLogin(ctx, app, db, user, ip) runs the steps POST /login takes after authentication, for a caller that authenticated the user another way (a social sign-in): it restores a soft-deleted account and sends the reactivate mail, records ip as last_ip_address and touches last_seen (a failure there is only logged). It checks no password, throttle, activation or ban and fires no event; the caller does those checks.
  • RegistrationSettings(app) returns allow_registration, use_register_throttle, activate_mode and require_activation with their defaults (true, true, auto, true), and RegistrationsFromIP(ctx, db, ip) counts the accounts created from an IP in the last 60 minutes (/register refuses at 3 with the throttle on).
  • RefreshTTL(app) is the refresh window, golem15.user.jwt.refresh_ttl minutes (default 20160), and RemoteIP(r) the host part of r.RemoteAddr, with no proxy handling (/login and /register use surf.ClientIP with http.trusted_proxies).
• classes: JWTSecret, GormUsers (the bouncer.UserProvider), LookupByEmail, UserPermissionGrants, UserGroupCodes, HasGroupCode, APITokenPrefix, MintAPIToken, HashAPIToken and RevokeAPIToken, plus the activation/reset, throttle, mail locale and event helpers. RegisterEvent carries User and Payload map[string]any, a read-only copy of the register input without the password keys. For the admin and for other plugins it also has:
  • MergedPermissions(ctx, db, userID), HasPermission(merged, code) and UserHasPermission(ctx, db, userID, code), the frontend permission resolver, and FrontendPermissionOptions(ctx, db), the catalogue by tab and code.
  • PermissionManagePrivilegedGroups, PrivilegedGroupCodes(cfg), IsPrivilegedCode(codes, code), PrivilegedGroupIDs(ctx, db, codes) and IsPrivilegedMember(ctx, db, codes, userID), the privileged-group rule.
  • ActivateUsers, DeactivateUsers, RestoreUsers, BanUsers, UnbanUsers, UnsuspendUser, ThrottleStates and ForceDeleteCleanup, the user actions the admin runs. Each takes the handle of the caller's transaction.
  • RevokeUserAccess(ctx, db, userIDs) ends every session JWT issued before the current second (it stamps users.tokens_valid_after, deactivated rows included) and revokes every personal API token of the users. DeactivateUsers and BanUsers call it; an application may call it for its own offboarding and after writing a ban directly to user_throttle.
  • TouchLastSeen(ctx, db, userID).
  • OAuthProvider (Name, Label) and OAuthProviderSource (EnabledOAuthProviders(ctx), KnownOAuthProviders()), the seam a social-login plugin publishes with an explicit type argument, app.Publish[classes.OAuthProviderSource](src), so the lookup finds it. GET /oauth-providers lists its enabled providers in order; the unlink routes accept its known names.
  • EndSession(ctx, app, w, r) is what POST /logout runs: it blacklists every session JWT the request carries (bearer header, token and auth_token cookies) that verifies, an expired one too while its refresh window is open, until that window closes, writes the forget cookies described under JWT sessions, and returns the subject of the token the guard would read ("" when there is none or it does not verify); only a failing blacklist write is an error.
  • SessionToken(r), the session JWT the jwt guard reads from a request (bearer header, then the token and auth_token cookies; "" when there is none); SessionTokenCookie(r), the name of the session cookie that supplied that token ("" when the bearer header did or there is none), which POST /refresh uses to rewrite the auth.cookie cookie; and SessionCookieNames(), a copy of that cookie list to pass to bouncer.NewJWTGuard, so a handler's own guard reads the same token.
  • RequestUser(ctx, app, r) and EndRequestSession(ctx, app, w, r), for handlers that serve signed-in and anonymous browsers on one route (an OAuth provider's authorize page). RequestUser reads and checks the session JWT exactly as the jwt guard does (bearer header, then the token and auth_token cookies, the blacklist, tokens_valid_after) and returns the user, or nil for an anonymous, invalid, expired or blacklisted request and for a soft-deleted user; only an infrastructure failure is an error. EndRequestSession is the best-effort EndSession: it revokes and forgets the same way (the forget cookie of bouncer.LoadCookieConfig), but a blacklist failure is logged, never returned.
  • AvatarURL(ctx, app, user, size), the display picture rule of the user payload at any size: the avatar thumbnail (size by size, mode auto) when the user has an avatar and a file bucket is published, the file path when the thumbnail fails, otherwise the gravatar URL. The URL may be protocol-relative or relative. The payload's avatar_url comes from it at 128.
  • HandleGenerator, AssignHandle(ctx, db, user), CreatedEvent / CreatedEventName, DeletingEvent / DeletingEventName, DeactivatingEvent / DeactivatingEventName, AuthorizeUser and RegisterUserAuthorizer.
• middleware: APITokenGuard, Scope, Permission and BearerToken.
• models: User, Throttle, Organisation, UserGroup, UsersGroup (the users_groups pivot), APIToken, OAuthIdentity, FrontendPermission and PermissionSet. PermissionSet reads a stored permission column tolerantly (NULL, an empty string, [], numeric strings) and writes a JSON object of integers; ParsePermissionSet and PermissionSet.Text do the same for a column that is a plain string on its model. UserGroup.UsersCount is filled only by a query that selects users_count (the admin list does). Organisation.Members is the relation behind the members manager, Organisation.AttachRelations declares its avatar (OrganisationAvatarField), and Slugify is the slug rule. User.FilterScope answers the admin list scope FilterByGroup, and User.AttachRelations declares the avatar (AvatarField). User.RegisterFillable is the registration allow-list; User.Fillable is the wider mass-assignment backstop of the admin Users form (cabana intersects it with the form's fields) and of trusted application code.
• updates: the gormigrate migrations, returned by updates.All().
• console: RequirePasswordChange, BackfillHandles and APITokenCommands.

Configuration

Defaults live in config/config.yaml and are merged under golem15.user.*. Any key can be overridden by an environment variable in the framework's SUMMER_ form.

Key	Default	Meaning
golem15.user.jwt.secret	""	HS256 signing secret. Required: boot fails while it is empty. Set it with SUMMER_GOLEM15__USER__JWT__SECRET; there is no production default.
golem15.user.jwt.ttl	60	Access token lifetime in minutes.
golem15.user.jwt.refresh_ttl	20160	Refresh window in minutes.
golem15.user.jwt.blacklist_grace	0	Grace period in seconds for a blacklisted token.
golem15.user.jwt.leeway	0	Clock leeway in seconds (declared for parity, not read yet).
golem15.user.jwt.blacklist_sweep_interval	10m	How often expired blacklist rows are deleted (a Go duration).
golem15.user.jwt.token_cookie	false	When on, POST /login, POST /register (when it signs the new account in) and POST /activate-by-code set the HttpOnly session cookie with the auth.cookie.* attributes (bouncer.LoadCookieConfig; Max-Age refresh_ttl) and leave token out of the body (user, and message on activate-by-code, stay). When off, the token is in the body and no cookie is set. The twin of golem15.sociallogin.token_cookie.
golem15.user.activation.require_activation	true	Whether an account must be activated before login. When true, POST /login refuses a not-activated account (the opaque invalid-login answer, counted as a failed attempt) and /register in admin mode returns no token; when false, both sign such an account in.
golem15.user.activation.activate_mode	auto	auto, user (mailed code) or admin.
golem15.user.activation.reset_ttl_minutes	60	Password reset code lifetime.
golem15.user.activation.activation_ttl_hours	72	Activation code lifetime.
golem15.user.registration.allow_registration	true	Whether POST /register accepts new accounts.
golem15.user.registration.use_register_throttle	true	Whether registration is limited to three accounts per IP an hour.
golem15.user.throttle.attempt_limit	5	Failed logins before suspension.
golem15.user.throttle.suspension_minutes	15	Suspension length.
golem15.user.throttle.use_throttle	true	Whether login throttling is on.
golem15.user.password.bcrypt_cost	10	bcrypt cost for new password hashes.
golem15.user.password.min_length	8	Minimum password length.
golem15.user.password.public_routes	true	When false, POST /login, POST /forgot-password and POST /reset-password are not registered and answer 404 like any unknown path; POST /register (still gated by allow_registration and guarded by golem15.user.turnstile) and every other route stay. It is read when the routes are built, so a change needs a restart. It takes true or false, also as a string (SUMMER_GOLEM15__USER__PASSWORD__PUBLIC_ROUTES=false); an empty value means true; any other value fails boot.
golem15.user.api_tokens.prefix	usr_	Prefix for newly minted and accepted shared API-token secrets. Override an existing application's legacy prefix without creating a plugin-specific token table.
golem15.user.privileged_groups	[admin]	Codes of the privileged user groups. Membership of such a group, the group's code and its delete, and the email, password and permanent delete of its members need golem15.users.manage_privileged_groups. Read on every request. An empty list protects no group.
golem15.user.turnstile	""	Cloudflare Turnstile on POST /login and POST /register (only /register while golem15.user.password.public_routes is false). Empty adds nothing; open or closed appends the framework's turnstile:open or turnstile:closed middleware to those two routes only (summercms v0.3.0 and later; secret in turnstile.secret, token in the turnstile_token field). open lets requests pass when Cloudflare is unreachable, closed refuses them. Any other value fails boot.

CLI commands

Command	Purpose	Example
user:require-password-change <email>	Flag an account so its next session must set a new password. Ends with Password change required for <email>.	bin/<app> user:require-password-change jane@example.com
user:backfill-handles	Assign a unique handle to every user row that still has none, with a progress bar. Ends with Assigned handles to N user(s).	bin/<app> user:backfill-handles
user:token:create <email> [--name api] [--scopes read,write] [--expires RFC3339] [--json]	Create an application-wide API token and print its secret once (also under -q); --json prints the token and its details as one object.	bin/<app> user:token:create jane@example.com --scopes read --json
user:token:list	List token metadata without secrets or hashes; --json prints a JSON array with the expiry, revocation and last-use times.	bin/<app> user:token:list --json
user:token:revoke <id>	Revoke a shared API token immediately.	bin/<app> user:token:revoke 12

Each command uses the database the serve command published or, run from the console, opens one from database.dsn (and loads the encryption keys from app.key) for its duration. bin/<app> help <command> shows each command's long help and examples. The plugin logs through the component user (log.components.user in config/log.yaml).

Dependencies

• The SummerCMS framework v0.4.3, git.golem15.com/golem15/summercms (modules backpack, bonfire, bouncer, diary, pact, party, surf and others).
• The organisation role cleanup of the admin (members manager and user form) uses cabana's ClearOnChange, added in SummerCMS v0.4.3.
• gormigrate, GORM, golang-jwt and gocloud.dev, as pinned in go.mod.
• testcontainers-go for the Postgres-backed tests.

Testing

go test -short ./...    # fast run, no Docker
go test ./...           # full run, starts Postgres with testcontainers (needs Docker)

TestRegisterCORSPath reads the host application's config/http.yaml, so run the tests inside an application checkout where the plugin is mounted at plugins/golem15/user.

TestCommandsDocumented (in -short) logs, without failing, each command whose help lacks a description, long help, examples or an option description (bonfire.CheckDocs).

TestRegisterIgnoresProtectedFields posts organisation, IP and account-flag keys to /register and RegisterUser and checks that only the allow-listed columns and the server-side IP are stored; TestRegisterListenerErrors checks that failing register and created listeners do not fail the registration.

TestOffboarding runs the admin deactivate and ban bulk actions and checks that the user's older session JWT and personal API token stop working, that a password login restores a deactivated account with a working token while the old credentials stay dead, and that unban revives nothing; TestRefreshSubjectChecks covers the /refresh subject checks; TestRevokeUserAccess (in classes) covers the revocation writes.

TestLogoutEndsTheSession signs in through POST /login and logs out with the bearer header, with only the token or auth_token cookie, and with both a bearer and a different cookie token, then checks that the token is refused on a jwt.auth route, at /fetch and at /refresh, each through every carrier (bearer header, token cookie, auth_token cookie), that the forget cookies match the token cookie's attributes (also with a configured domain and SameSite), that the blacklist row lasts for the refresh window so /refresh stays refused after the sweep that follows the access token's expiry, that an expired but refreshable token is revoked, and which tokens a logout refuses with 401.

TestBootBeforeDatabase boots in the serve order (party.Activate with no database, then lagoon.Publish, through newServeOrderEnv in admin_harness_test.go). It checks that the blacklist store and the GORM hooks are installed on Publish and not before, and that a token ended by POST /logout is refused on a jwt.auth route through every carrier, at /fetch and at /refresh, with its jwt_blacklist row. TestAppBlacklist (in -short) covers the guard's per-request store lookup: no store, delegation and a failing store.

TestSessionRoutesAcceptCookies checks that a session jwt.auth accepts through only the token or auth_token cookie is served by GET /fetch, POST /refresh (through token, the auth.cookie default, the rotated token comes back in a rewritten cookie with a {} body; through auth_token it comes in the body with no cookie; the old token is refused afterwards), POST /update, POST /change-password (the calling token stays valid) and POST /marketing-consent; that a request without credentials still gets the old 401 bodies; that the bearer header wins over a cookie exactly as on jwt.auth, an invalid bearer included; and that a cut-off token and a banned user are refused through the cookie.

TestLoginRequiresActivation pins the activation gate of POST /login: under the default and an explicit require_activation: true a not-activated account's correct password gets the byte-identical 401 (status, body, Content-Type and Cache-Control) of a wrong password, stamps no last_seen, adds one throttle attempt and suspends the account after attempt_limit refusals; require_activation: false and activated accounts sign in; a deactivated activated account is restored with the reactivate mail, and a deactivated not-activated account is refused and stays deactivated unless the key is off.

TestLoginThrottleClientIP sends failed logins through one trusted proxy (http.trusted_proxies). It checks that the throttle row carries the X-Forwarded-For client, and that this client is suspended while another client behind the same proxy still signs in. It also checks that without trusted proxies a changing X-Forwarded-For neither moves the counter nor escapes the suspension.

TestRefreshRewritesAuthCookie covers the cookie-carried POST /refresh: the token cookie rewritten with the rotated token and the LoadCookieConfig attributes (the old token refused, the new one served by /fetch and jwt.auth), auth_token and bearer refreshes left body-only (the bearer wins over a cookie), a configured cookie name and refresh window, refusals that set no cookie, and a broken auth.cookie block that answers the opaque 500 and rotates nothing. TestSessionTokenCookie (in -short) is the carrier table of classes.SessionTokenCookie.

TestTokenCookie covers golem15.user.jwt.token_cookie: off by default (body tokens, no cookie); on for POST /login, POST /register and POST /activate-by-code, with the session cookie serving /fetch and rotating through a cookie refresh and no token in the body; POST /tokens unaffected; a configured cookie name and refresh window; and a broken auth.cookie block that answers the opaque 500 and signs in, creates and activates nothing.

TestPasswordPublicRoutes (in -short) and TestPasswordPublicRoutesAnswer404 cover golem15.user.password.public_routes: unset, true and the config.yaml default register every route; false (also from a SUMMER_ variable) drops exactly the three password routes and keeps every other route and its middleware, the turnstile on /register included; an invalid value fails Routes. Through the assembled router the dropped routes (and a GET /login) answer exactly like an unknown path and sign in, mail and reset nothing, while the default answers are unchanged and /register, /fetch, /refresh and /logout still work.

TestAdminOrganisationMembershipClearsRole checks that the members manager's unlink and link and a Users form save that changes the organisation clear organisation_role, that a save keeping the organisation keeps it, and that deleting an organisation clears both columns.

The admin tests (TestAdmin*) boot the plugin with the admin API mounted on a database of their own and sign in backend administrators with a chosen permission set; the helpers are in admin_harness_test.go.