admin

type Action[T any] struct {
	// Name is the policy ability, the URL segment and the audit-log action:
	// a lower-camel identifier of at most 16 characters ([a-z][a-zA-Z0-9]*),
	// not one of viewAny, view, create, update, delete or edit.
	Name string
	// Label is the button text (default: Name humanized).
	Label string
	// Reason asks for a reason on the confirmation page (required, at most
	// MaxReason characters); Run receives it and the audit log records it
	// under ReasonKey.
	Reason bool
	// Bulk also offers the action on the rows selected in the list (at
	// most MaxBulk at once); every record must pass the policy or none
	// runs.
	Bulk bool
	// Run performs the action. Changes it makes to rec's fields are saved
	// after it returns (orm.Update) and recorded in the audit log; other
	// writes go through tx so they roll back with the rest.
	Run func(ctx context.Context, tx *database.Tx, rec *T, reason string) error
}

type AnyResource interface {
	// contains filtered or unexported methods
}

type AuditLog struct {
	ID int64 `db:"id"`
	// ActorID is the AuthID of the user who made the change.
	ActorID string `db:"actor_id"`
	// Resource is the resource slug ("posts").
	Resource string `db:"resource"`
	// RecordID is the primary key of the changed record.
	RecordID string `db:"record_id"`
	// Action is ActionCreate, ActionUpdate, ActionDelete or the Name of a
	// custom Action.
	Action string `db:"action"`
	// Changes maps changed columns to their values before and after.
	// Sensitive columns only record that they changed.
	Changes   orm.JSON[map[string]Change] `db:"changes"`
	CreatedAt time.Time                   `db:"created_at"`
}

type Change struct {
	Before   any  `json:"before,omitempty"`
	After    any  `json:"after,omitempty"`
	Redacted bool `json:"redacted,omitempty"`
}

type Config struct {
	// DB stores the resources and the audit log (required).
	DB *database.DB
	// Guard authenticates admins (required), e.g. the "web" session guard.
	// Guests are redirected to the route named "login" (401 for JSON).
	Guard auth.Checker
	// Authorizer decides the panel and policy abilities, usually an
	// authz.Gate. Nil uses the router's Services.Authorizer; with neither,
	// everything is denied.
	Authorizer web.Authorizer
	// Prefix is the URL prefix (default "/admin").
	Prefix string
	// Ability is the gate ability required for every page (default
	// "admin").
	Ability string
	// Title is shown in the header (default "Admin").
	Title string
	// Views overrides embedded templates by path: layouts/admin.html,
	// index.html, show.html, form.html, delete.html, dashboard.html,
	// audit.html, flags.html, action.html, partials/pager.html.
	Views fs.FS
	// Flags adds a page at <Prefix>/_flags to change the global value of
	// the registered feature flags (app.Flags()); it needs the
	// AbilityFlags gate ability. Without registered flags the page and its
	// routes do not exist. Locked flags are shown read-only. Every change
	// is a "flags.changed" audit event and an audit-log entry; a save that
	// leaves the value as it was records nothing.
	Flags *flags.Flags

	// TwoFactor makes two-factor authentication mandatory for the panel:
	// it reports whether the admin authenticated on ctx (auth.UserFrom)
	// has 2FA enabled. The 2FA state lives in the app (the install:auth
	// scaffold's users.two_factor_enabled), so the panel asks. false is 403
	// with an "admin.2fa_required" security event; an error is 403 too
	// (fail closed). Nil does not require 2FA.
	TwoFactor func(ctx context.Context) (bool, error)
	// MaxSessionAge, when positive, is the oldest a session may be to use
	// the panel, counted from its creation (session.CreatedAt), a stricter
	// limit than the app's SESSION_LIFETIME. An older session is
	// invalidated (signed out of every guard, an "admin.session_expired"
	// security event) and the browser is sent to log in again. A
	// remember-me cookie logs the user back in with a new session: turn
	// remember-me off for admins when the cap must force a password.
	MaxSessionAge time.Duration
	// IdleTimeout, when positive, ends a session that has not touched a
	// guarded admin route for that long. The clock is the session value
	// "admin.idle_at", updated only by Guard (and the routes Mount
	// registers), not by the rest of the app. An idle session is
	// invalidated (an "admin.session_idle" security event) and the browser
	// is sent to log in again. Activity elsewhere does not refresh it.
	IdleTimeout time.Duration
	// AllowCIDRs, when not empty, limits the panel to client IPs
	// (web.Ctx.IP, trusted-proxy aware) inside one of the prefixes. Others
	// get 403 with an "admin.ip_denied" security event, before any login
	// redirect. The embedded CSS and JS stay public.
	AllowCIDRs []netip.Prefix
	// Now is the clock for MaxSessionAge and IdleTimeout (tests); defaults
	// to time.Now.
	Now func() time.Time
}

type Panel struct {
	// contains filtered or unexported fields
}

type Resource[T any] struct {
	// contains filtered or unexported fields
}

type Saved[T any] struct {
	// Tx is the panel transaction the record was written in: write related
	// rows through it, and use Tx.AfterCommit for work that must only
	// happen once the save is committed (events, mail, cache).
	Tx *database.Tx
	// Action is ActionCreate or ActionUpdate.
	Action string
	// Record is the record as written.
	Record *T
	// Before is a copy of the record before the form was applied; nil on
	// create.
	Before *T
	// Virtual holds the parsed values of the submitted Virtual fields, by
	// schema key.
	Virtual map[string]any
}