accounts

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 48 Imported by: 0

Documentation

Overview

Package accounts implements sign-in (identifier first, password, passkeys, two-factor, recovery codes), sessions, password resets, accepting invitations, the signed-in person's profile and security settings, and the first sign-in setup of an instance.

Index

Constants

View Source
const ResetTTL = 15 * time.Minute

ResetTTL is how long a password reset link works.

Variables

This section is empty.

Functions

func CreateResetToken

func CreateResetToken(ctx context.Context, q *store.Queries, userID uuid.UUID, source string, now time.Time) (string, time.Time, error)

CreateResetToken stores a one-time reset token for a user and returns it. Earlier unused tokens stop working.

func Register

func Register(h huma.API, s *Service)

Register adds the accounts operations.

func ResetLink(publicURL, token string) string

ResetLink builds the link of a reset token.

Types

type AccountAvatarInput

type AccountAvatarInput struct {
	Data []byte `json:"data" doc:"PNG or JPEG, up to 2 MB, base64"`
}

AccountAvatarInput is a PNG or JPEG photo, base64-encoded in JSON.

type AccountEmailChangeInput

type AccountEmailChangeInput struct {
	Email string `json:"email" format:"email" maxLength:"254"`
	// Password confirms the change for accounts that have one.
	Password string `json:"password,omitempty" maxLength:"1024"`
}

AccountEmailChangeInput asks to move the account to a new address.

type AccountEmailChangeStarted

type AccountEmailChangeStarted struct {
	Email     string    `json:"email"`
	ExpiresAt time.Time `json:"expiresAt"`
}

AccountEmailChangeStarted says where the verification link went.

type AccountEmailChanged

type AccountEmailChanged struct {
	Email string `json:"email"`
}

AccountEmailChanged is returned after the new address is confirmed.

type AccountIdentity

type AccountIdentity struct {
	Kind   string `json:"kind" enum:"google,microsoft,github,sso"`
	Name   string `json:"name" example:"GitHub"`
	Preset string `json:"preset,omitempty" doc:"SSO preset, for the icon"`
	Linked bool   `json:"linked"`
	// ID identifies a linked identity (for unlinking).
	ID       string `json:"id,omitempty"`
	Username string `json:"username,omitempty" example:"linh-nguyen"`
	Email    string `json:"email,omitempty"`
	// Notes follow the account: "org acme-eng", "acme.io", "break-glass password kept".
	Notes []string `json:"notes"`
	// LinkURL starts linking (social sign-in).
	LinkURL   string `json:"linkUrl,omitempty"`
	CanUnlink bool   `json:"canUnlink"`
	// Managed: SSO is enforced for the domain; the organization manages it.
	Managed bool `json:"managed"`
	// OnlyMethod: this is the last way to sign in.
	OnlyMethod   bool   `json:"onlyMethod"`
	UnlinkReason string `json:"unlinkReason,omitempty"`
}

AccountIdentity is one row of Connected sign-ins.

type AccountOverview

type AccountOverview struct {
	Profile       AccountProfile             `json:"profile"`
	Password      AccountPassword            `json:"password"`
	Passkeys      []AccountPasskey           `json:"passkeys"`
	TwoFactor     AccountTwoFactor           `json:"twoFactor"`
	Identities    []AccountIdentity          `json:"identities"`
	Workspaces    []AccountWorkspace         `json:"workspaces"`
	Notifications notify.NotificationSummary `json:"notifications"`
	SessionPolicy AccountSessionPolicy       `json:"sessionPolicy"`
}

AccountOverview is the Account & security screen (A5 §5.6).

type AccountPasskey

type AccountPasskey struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Kind: platform (built into a device or password manager) or security_key.
	Kind        string     `json:"kind" enum:"platform,security_key,unknown"`
	Provider    string     `json:"provider,omitempty" example:"iCloud Keychain"`
	CreatedAt   time.Time  `json:"createdAt"`
	LastUsedAt  *time.Time `json:"lastUsedAt,omitempty"`
	ThisSession bool       `json:"thisSession" doc:"This session signed in with the passkey"`
}

type AccountPassword

type AccountPassword struct {
	Set           bool       `json:"set"`
	ChangedAt     *time.Time `json:"changedAt,omitempty"`
	MinLength     int        `json:"minLength"`
	BreachedCheck bool       `json:"breachedCheck"`
	// SSOOnly is true when there is no ReputeCast password and an SSO
	// identity signs the person in; ManagedBy names the provider.
	SSOOnly   bool   `json:"ssoOnly"`
	ManagedBy string `json:"managedBy,omitempty"`
}

AccountPassword is the Password section. It is hidden for people who only sign in through SSO.

type AccountPendingEmail

type AccountPendingEmail struct {
	Email     string    `json:"email"`
	SentAt    time.Time `json:"sentAt"`
	ExpiresAt time.Time `json:"expiresAt"`
}

AccountPendingEmail is an email change waiting for its verification link.

type AccountProfile

type AccountProfile struct {
	Name            string               `json:"name"`
	Email           string               `json:"email"`
	Timezone        string               `json:"timezone"`
	AvatarColor     string               `json:"avatarColor"`
	AvatarURL       string               `json:"avatarUrl,omitempty"`
	IsInstanceAdmin bool                 `json:"isInstanceAdmin"`
	PendingEmail    *AccountPendingEmail `json:"pendingEmail,omitempty"`
}

AccountProfile is how the person appears to the team.

type AccountProfileInput

type AccountProfileInput struct {
	Name     string `json:"name" minLength:"1" maxLength:"80"`
	Timezone string `json:"timezone" minLength:"1" maxLength:"64"`
}

AccountProfileInput changes the name and timezone.

type AccountSession

type AccountSession struct {
	ID      string `json:"id"`
	Device  string `json:"device" example:"MacBook Pro"`
	OS      string `json:"os" example:"macOS 26"`
	Browser string `json:"browser" example:"Chrome 141"`
	IP      string `json:"ip,omitempty"`
	// Location is approximate and only known when the instance has a local
	// geolocation source; IPs are never sent to third parties.
	Location     string    `json:"location,omitempty" example:"New York, US"`
	Method       string    `json:"method" example:"password+totp"`
	CreatedAt    time.Time `json:"createdAt"`
	LastActiveAt time.Time `json:"lastActiveAt"`
	Current      bool      `json:"current"`
}

AccountSession is one signed-in browser or device.

type AccountSessionList

type AccountSessionList struct {
	Items []AccountSession `json:"items"`
}

AccountSessionList is GET /me/sessions.

type AccountSessionPolicy

type AccountSessionPolicy struct {
	Lifetime string `json:"lifetime" example:"14 days"`
	Idle     string `json:"idle" example:"12 hours"`
}

AccountSessionPolicy is the instance session policy, for the caption.

type AccountSessionsRevoked

type AccountSessionsRevoked struct {
	Revoked int64 `json:"revoked"`
}

AccountSessionsRevoked says how many sessions were signed out.

type AccountTwoFactor

type AccountTwoFactor struct {
	TOTP      bool       `json:"totp"`
	TOTPSetAt *time.Time `json:"totpSetAt,omitempty"`
	TOTPLabel string     `json:"totpLabel,omitempty" example:"1Password"`
	// Required is true when the instance policy requires a second factor:
	// for everyone, or because the person holds a sensitive permission.
	Required       bool       `json:"required"`
	RequiredBy     string     `json:"requiredBy,omitempty" enum:"everyone,sensitive"`
	RequiredReason string     `json:"requiredReason,omitempty"`
	GraceUntil     *time.Time `json:"graceUntil,omitempty"`
	// ViaIdP is true for SSO-only accounts: the identity provider enforces it.
	ViaIdP             bool       `json:"viaIdp"`
	RecoveryRemaining  int        `json:"recoveryRemaining"`
	RecoveryTotal      int        `json:"recoveryTotal"`
	RecoveryLastUsedAt *time.Time `json:"recoveryLastUsedAt,omitempty"`
}

AccountTwoFactor is the Authenticator app section and recovery codes.

type AccountWorkspace

type AccountWorkspace struct {
	ID          string `json:"id"`
	Slug        string `json:"slug"`
	Name        string `json:"name"`
	RoleKey     string `json:"roleKey"`
	RoleName    string `json:"roleName"`
	Members     int64  `json:"members"`
	CanLeave    bool   `json:"canLeave"`
	LeaveReason string `json:"leaveReason,omitempty"`
}

AccountWorkspace is one row of My workspaces.

type AvatarImage

type AvatarImage struct {
	ContentType  string    `header:"Content-Type"`
	CacheControl string    `header:"Cache-Control"`
	LastModified time.Time `header:"Last-Modified"`
	Body         []byte
}

AvatarImage is a profile photo response.

type CheckLine

type CheckLine struct {
	Status string `json:"status" enum:"ok,warn,bad,skipped"`
	Detail string `json:"detail"`
	// contains filtered or unexported fields
}

CheckLine is one row of the public URL check. Its detail is kept as a message too, stored with the check as "i18n" (not part of the API).

func (CheckLine) In

func (c CheckLine) In(l i18n.Lang) CheckLine

In writes the line in a reader's language (lines stored before, without a message, keep their English) and drops the kept message.

func (CheckLine) MarshalJSON

func (c CheckLine) MarshalJSON() ([]byte, error)

MarshalJSON adds the kept message ("i18n") to the line.

func (*CheckLine) UnmarshalJSON

func (c *CheckLine) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a line and its kept message.

type CreatedWorkspace

type CreatedWorkspace struct {
	ID   string `json:"id"`
	Slug string `json:"slug"`
	Name string `json:"name"`
}

CreatedWorkspace is returned after creating a workspace.

type Device

type Device struct {
	Device  string // "Mac", "iPhone", "Windows PC"
	OS      string // "macOS", "iOS 18", "Windows"
	Browser string // "Chrome 141", "Safari 18", "Edge 141"
}

Device describes the browser and computer a session was created from.

func ParseUserAgent

func ParseUserAgent(ua string) Device

ParseUserAgent extracts a readable device, OS and browser from a user agent string. It is deliberately small: the session list only needs a recognisable label, and browsers freeze most details in the UA anyway (macOS always reports 10.15, Windows 10 and 11 look the same).

type ExternalIdentity

type ExternalIdentity struct {
	Kind       string // google, microsoft, github, sso
	ProviderID *uuid.UUID
	// ProviderName is "Google", "GitHub" or the SSO provider's name.
	ProviderName string
	Subject      string
	Email        string
	// EmailVerified: the IdP vouches for Email the way its sign-in takes it
	// (internal/sso decides for each provider). Only then may joining create
	// an account for the email.
	EmailVerified bool
	Name          string
	Username      string
	Details       json.RawMessage
	MFA           bool
	Metadata      map[string]any
}

ExternalIdentity is an identity an IdP verified for an invitee.

type ExternalResult

type ExternalResult struct {
	// Cookie is the session cookie (nil while a second factor is pending).
	Cookie *http.Cookie
	// Next is where to go after signing in.
	Next string
	// Challenge is set when the person still has to confirm their own
	// second factor because the IdP didn't assert one.
	Challenge   string
	Methods     []string
	PasskeyHint string
}

ExternalResult tells the callback where to send the browser.

type ExternalSignIn

type ExternalSignIn struct {
	User store.User
	// Method is "sso", "google", "microsoft" or "github".
	Method string
	// MFA: the IdP asserted a second factor (amr) or is trusted to enforce it.
	MFA      bool
	Remember bool
	// Metadata is added to the signin.succeeded audit entry (provider, amr…).
	Metadata map[string]any
}

ExternalSignIn is a sign-in an identity provider confirmed.

type IdentifyResult

type IdentifyResult struct {
	Email string `json:"email"`
	// Next is "password" for the password step or "sso" when the email's
	// domain enforces single sign-on.
	Next string    `json:"next" enum:"password,sso"`
	SSO  *SSOStart `json:"sso,omitempty"`
	// BreakGlass says Owners of this domain may still use a password. It is
	// shown for every enforced domain, so it reveals nothing about the account.
	BreakGlass bool `json:"breakGlass"`
}

IdentifyResult tells the sign-in page what to show after the email step.

type InstanceBasics

type InstanceBasics struct {
	Name        string `json:"name" minLength:"1" maxLength:"80"`
	PublicURL   string `json:"publicUrl" format:"uri" maxLength:"300"`
	Timezone    string `json:"timezone" maxLength:"64"`
	UpdateCheck bool   `json:"updateCheck"`
	// DefaultLanguage is the instance's default app language; the region
	// format follows it. Unchanged when omitted.
	DefaultLanguage string `json:"defaultLanguage,omitempty" enum:"en,de,es,fr,vi"`
}

InstanceBasics is step 4 of the first sign-in.

type InvitationAcceptInput

type InvitationAcceptInput struct {
	Name     string `json:"name,omitempty" maxLength:"80"`
	Password string `json:"password,omitempty" maxLength:"1024"`
	// Passkey joins without a password: the account is created and signed
	// in, and the browser adds a passkey next (POST /me/passkeys). Until it
	// has one, a password reset link is the way back in.
	Passkey bool `json:"passkey,omitempty"`
}

InvitationAcceptInput creates the account of a new member. Existing accounts accept while signed in and send no body.

type InvitationAccepted

type InvitationAccepted struct {
	Workspace     string `json:"workspace" doc:"Workspace slug"`
	WorkspaceName string `json:"workspaceName"`
	RoleName      string `json:"roleName"`
	Email         string `json:"email"`
	// NewAccount is true when joining created the account (and signed in).
	NewAccount bool `json:"newAccount"`
	// HasSecondFactor tells the app whether to offer passkey and 2FA setup.
	HasSecondFactor bool                `json:"hasSecondFactor"`
	TwoFactor       InvitationTwoFactor `json:"twoFactor"`
	Next            string              `json:"next"`
}

InvitationAccepted is returned after joining.

type InvitationAgency

type InvitationAgency struct {
	// Name is the agency's ("Northwind Studio").
	Name string `json:"name"`
	// ClientRole: the invitation is for Client approver or Client viewer.
	ClientRole bool `json:"clientRole"`
	// RoleLine is what the role sees, in one line: "You'll see campaigns
	// and reports."
	RoleLine string `json:"roleLine,omitempty"`
	// Passkey: the sign-in policy allows passkeys, so the page offers
	// "Create a passkey and join" first and a password second.
	Passkey bool `json:"passkey"`
}

InvitationAgency is the client variant of an invitation (agencies, channels and agencies brief §6): the workspace is a client of the agency that runs this instance. The page explains the role in one line and says who manages the workspace.

type InvitationPasswordPolicy

type InvitationPasswordPolicy struct {
	MinLength     int  `json:"minLength"`
	BreachedCheck bool `json:"breachedCheck"`
}

InvitationPasswordPolicy is the password policy shown while creating a password.

type InvitationRequestResult

type InvitationRequestResult struct {
	Status  string `json:"status" enum:"sent,already_sent"`
	Inviter string `json:"inviter"`
}

InvitationRequestResult says whether the inviter was asked.

type InvitationTwoFactor

type InvitationTwoFactor struct {
	Required   bool       `json:"required"`
	Reason     string     `json:"reason,omitempty"`
	GraceDays  int        `json:"graceDays"`
	GraceUntil *time.Time `json:"graceUntil,omitempty"`
}

InvitationTwoFactor says whether the new member must set up two-factor.

type InvitationView

type InvitationView struct {
	Status        string `json:"status" enum:"pending,expired,revoked,accepted"`
	Email         string `json:"email"`
	WorkspaceName string `json:"workspaceName"`
	WorkspaceSlug string `json:"workspaceSlug"`
	InviterName   string `json:"inviterName"`
	// InviterUnknown: the inviter's account is gone, so InviterName names an
	// admin of the workspace ("An admin of Acme Newsletter").
	InviterUnknown bool   `json:"inviterUnknown,omitempty"`
	RoleKey        string `json:"roleKey"`
	RoleName       string `json:"roleName"`
	// Scope restricts the role ("Beta Program list only"); empty for everything.
	Scope string `json:"scope,omitempty"`
	// Description says what the role can do, in one or two sentences.
	Description string     `json:"description"`
	Message     string     `json:"message,omitempty" doc:"Personal message from the inviter"`
	SentAt      time.Time  `json:"sentAt"`
	ExpiresAt   time.Time  `json:"expiresAt"`
	RevokedAt   *time.Time `json:"revokedAt,omitempty"`
	AcceptedAt  *time.Time `json:"acceptedAt,omitempty"`
	// AccountExists: the email already has an account, so the invitee signs
	// in to accept instead of creating a password.
	AccountExists bool `json:"accountExists"`
	// SignedInAs is the email of the browser's current session, if any.
	SignedInAs string `json:"signedInAs,omitempty"`
	// Password sign-up is unavailable when the domain enforces SSO.
	PasswordAllowed bool                     `json:"passwordAllowed"`
	PasswordPolicy  InvitationPasswordPolicy `json:"passwordPolicy"`
	Social          []string                 `json:"social" doc:"Social sign-in providers to join with: google, microsoft, github"`
	SSO             *SSOStart                `json:"sso,omitempty"`
	TwoFactor       InvitationTwoFactor      `json:"twoFactor"`
	// Language is the invitation's (the instance default when it has none):
	// the page reads in it unless the visitor picks another.
	Language string `json:"language,omitempty" example:"en"`
	// Agency is set when the workspace is a client of the instance's
	// agency: the page's client variant (invite_agency.go).
	Agency *InvitationAgency `json:"agency,omitempty"`
}

InvitationView is what the invitee sees before joining (A5 §5.4).

type Me

type Me struct {
	User       MeUser        `json:"user"`
	Workspaces []MeWorkspace `json:"workspaces"`
	Instance   MeInstance    `json:"instance"`
	// Pending is set when the person must finish something before using the
	// app: password_change, two_factor_setup or instance_setup.
	Pending string `json:"pending,omitempty" enum:"password_change,two_factor_setup,instance_setup"`
}

Me is GET /me.

type MeInstance

type MeInstance struct {
	Name          string `json:"name"`
	PublicURL     string `json:"publicUrl"`
	Version       string `json:"version"`
	LatestVersion string `json:"latestVersion,omitempty"`
	SetupComplete bool   `json:"setupComplete"`
	// DefaultLanguage and DefaultRegionFormat apply to members who haven't chosen.
	DefaultLanguage     string `json:"defaultLanguage,omitempty" example:"en"`
	DefaultRegionFormat string `json:"defaultRegionFormat,omitempty" example:"standard"`
	// Languages are the app languages the server answers in (the pseudo-locale when it's on).
	Languages []applang.LanguageOption `json:"languages,omitempty"`
}

MeInstance is what the shell shows about the installation.

type MeUser

type MeUser struct {
	ID              string     `json:"id"`
	Email           string     `json:"email"`
	Name            string     `json:"name"`
	AvatarColor     string     `json:"avatarColor"`
	AvatarURL       string     `json:"avatarUrl,omitempty"`
	Timezone        string     `json:"timezone"`
	IsInstanceAdmin bool       `json:"isInstanceAdmin"`
	BreakGlass      bool       `json:"breakGlass"`
	HasPassword     bool       `json:"hasPassword"`
	TOTP            bool       `json:"totp"`
	Passkeys        int        `json:"passkeys"`
	RecoveryCodes   int        `json:"recoveryCodes" doc:"Unused recovery codes"`
	TwoFAGraceUntil *time.Time `json:"twoFAGraceUntil,omitempty"`
	// Preferences are the app language and region format the person chose
	// (Account & security › Language & region).
	Preferences applang.MemberLanguage `json:"preferences,omitempty"`
	// LanguageSuggestionAnswered: the member answered "Your browser prefers …",
	// so it isn't offered again.
	LanguageSuggestionAnswered bool `json:"languageSuggestionAnswered,omitempty"`
	// Theme is the light or dark theme the person chose (Account & security ›
	// Appearance); system follows the device.
	Theme string `json:"theme" enum:"system,light,dark"`
}

MeUser is the signed-in person.

type MeWorkspace

type MeWorkspace struct {
	ID          string `json:"id"`
	Slug        string `json:"slug"`
	Name        string `json:"name"`
	RoleKey     string `json:"roleKey"`
	RoleName    string `json:"roleName"`
	MemberCount int64  `json:"memberCount"`
	Subscribers int64  `json:"subscribers"`
}

MeWorkspace is one workspace the person belongs to.

type PasskeyOptions

type PasskeyOptions struct {
	// Challenge identifies the ceremony; pass it back with the browser's answer.
	Challenge string `json:"challenge"`
	// Options are PublicKeyCredentialCreationOptionsJSON (registration) or
	// PublicKeyCredentialRequestOptionsJSON (sign-in) for navigator.credentials.
	Options json.RawMessage `json:"options"`
}

PasskeyOptions starts a WebAuthn ceremony in the browser.

type PasswordResetDone

type PasswordResetDone struct {
	Email string `json:"email"`
}

PasswordResetDone is returned after setting a new password.

type PasswordResetInfo

type PasswordResetInfo struct {
	Email     string    `json:"email"`
	ExpiresAt time.Time `json:"expiresAt"`
	MinLength int       `json:"minLength"`
	Breached  bool      `json:"breachedCheck" doc:"New passwords are checked against known breaches"`
}

PasswordResetInfo describes a usable reset link.

type PasswordResetRequest

type PasswordResetRequest struct {
	// Status: sent (generic: a link is on its way if the account exists),
	// email_unavailable (no System-stream provider yet: an instance admin
	// resets it with the CLI command) or sso (the password is managed by the
	// identity provider).
	Status string `json:"status" enum:"sent,email_unavailable,sso"`
	Email  string `json:"email"`
	// Command is the server command for email_unavailable.
	Command string    `json:"command,omitempty" example:"reputecast user reset-password --email aisha@acme.io"`
	SSO     *SSOStart `json:"sso,omitempty"`
	// ExpiresInMinutes is how long the emailed link works.
	ExpiresInMinutes int `json:"expiresInMinutes"`
}

PasswordResetRequest is the answer to "Email me a reset link". It never reveals whether an account exists, except that an email domain signs in with single sign-on (which the sign-in page shows anyway).

type PathID

type PathID struct {
	ID string `path:"id" format:"uuid"`
}

PathID is the {id} path parameter.

type PathToken

type PathToken struct {
	Token string `path:"token" minLength:"10" maxLength:"200"`
}

PathToken is the {token} path parameter of reset and invitation links.

type RecoveryCodes

type RecoveryCodes struct {
	Codes []string `json:"codes"`
}

RecoveryCodes are shown exactly once.

type SSOStart

type SSOStart struct {
	ProviderID string `json:"providerId"`
	Name       string `json:"name" example:"Google Workspace"`
	Preset     string `json:"preset"`
	StartURL   string `json:"startUrl" doc:"Navigate here to start the OIDC flow"`
}

SSOStart describes the identity provider a domain signs in with.

type Service

type Service struct {
	Pool           *pgxpool.Pool
	Q              *store.Queries
	Audit          *audit.Logger
	Box            *secrets.Box
	Cfg            *config.Config
	Mail           mailer.Sender
	Log            *slog.Logger
	Breach         *authn.BreachChecker
	Now            func() time.Time
	OnPolicyChange func()
	// OnPublicURL applies a public URL saved at the first sign-in (before and
	// after; empty means http.public_url), as Instance admin's save does.
	OnPublicURL func(ctx context.Context, before, after string)
}

Service holds the dependencies of the accounts domain.

func (*Service) AcceptInvitation

func (s *Service) AcceptInvitation(ctx context.Context, token string, in InvitationAcceptInput) (InvitationAccepted, *http.Cookie, error)

AcceptInvitation joins the workspace. Signed-in people accept with their account (it must be the invited email); new people create an account with a password, which signs them in.

func (*Service) AcceptInvitationExternal

func (s *Service) AcceptInvitationExternal(ctx context.Context, token string, id ExternalIdentity) (ExternalResult, error)

AcceptInvitationExternal joins the workspace of a pending invitation with an identity an IdP verified, whose email must be the invited one. An invitation link is easy to come by (anyone can create a workspace and invite any address), so the IdP's word counts only as far as sign-in takes it: a new account needs an email the IdP vouches for, and an account that already uses the email accepts only with an identity it already signs in with. Otherwise the person signs in first and accepts while signed in, as with a password. Domains under single sign-on join through their provider, as they sign in. New people get an account without a password and the identity linked.

func (*Service) Avatar

func (s *Service) Avatar(ctx context.Context, userID uuid.UUID) (*AvatarImage, error)

Avatar returns a person's photo to themselves and to people who share a workspace with them.

func (*Service) BeginPasskeyRegistration

func (s *Service) BeginPasskeyRegistration(ctx context.Context) (PasskeyOptions, error)

BeginPasskeyRegistration starts adding a passkey to the signed-in account.

func (*Service) BeginPasskeySignIn

func (s *Service) BeginPasskeySignIn(ctx context.Context) (PasskeyOptions, error)

BeginPasskeySignIn starts "Sign in with a passkey", which needs no email.

func (*Service) BeginTOTP

func (s *Service) BeginTOTP(ctx context.Context) (TOTPSetup, error)

BeginTOTP creates a pending authenticator secret (not active until confirmed).

func (*Service) BeginTwoFactorPasskey

func (s *Service) BeginTwoFactorPasskey(ctx context.Context, challenge string) (PasskeyOptions, error)

BeginTwoFactorPasskey starts confirming a password sign-in with a passkey.

func (*Service) CancelEmailChange

func (s *Service) CancelEmailChange(ctx context.Context) error

CancelEmailChange drops a pending email change.

func (*Service) ChangePassword

func (s *Service) ChangePassword(ctx context.Context, current, next string) error

ChangePassword replaces the caller's password. A temporary password from `reputecast install` is replaced the same way (current = the temporary one). An account without a password gets its first one only where no SSO provider manages it, and only from a session that signed in moments ago: there is no current password to ask for, and a password would otherwise let someone holding a stolen session cookie, or a person the IdP has since turned off, keep signing in.

func (*Service) CheckPasswordReset

func (s *Service) CheckPasswordReset(ctx context.Context, token string) (PasswordResetInfo, error)

CheckPasswordReset tells whether a reset link still works.

func (*Service) CheckPublicURL

func (s *Service) CheckPublicURL(ctx context.Context, raw string) (URLCheck, error)

CheckPublicURL resolves the host, checks the certificate and fetches /healthz. The lines are in English with their messages kept; callers answer with URLCheck.In.

func (*Service) CompleteExternalSignIn

func (s *Service) CompleteExternalSignIn(ctx context.Context, in ExternalSignIn) (ExternalResult, error)

CompleteExternalSignIn signs a person in after an identity provider confirmed them. When the IdP asserted no second factor and the person has one (authenticator or passkey), it asks for it like a password sign-in does; otherwise the session is created.

func (*Service) CompleteSetup

func (s *Service) CompleteSetup(ctx context.Context) error

CompleteSetup marks the instance as set up (after the first workspace exists).

func (*Service) ConfirmEmailChange

func (s *Service) ConfirmEmailChange(ctx context.Context, token string) (AccountEmailChanged, error)

ConfirmEmailChange applies a pending change with the link from the email. The person must be signed in to the same account.

func (*Service) ConfirmTOTP

func (s *Service) ConfirmTOTP(ctx context.Context, challenge, code string) (RecoveryCodes, error)

ConfirmTOTP activates the authenticator after a correct code and returns fresh recovery codes.

func (*Service) CreateWorkspace

func (s *Service) CreateWorkspace(ctx context.Context, name, timezone string) (CreatedWorkspace, error)

CreateWorkspace makes a new workspace with the caller as Owner.

func (*Service) FinishPasskeyRegistration

func (s *Service) FinishPasskeyRegistration(ctx context.Context, challenge string, credential json.RawMessage, name string) (AccountPasskey, error)

FinishPasskeyRegistration verifies the browser's answer and stores the passkey.

func (*Service) Identify

func (s *Service) Identify(ctx context.Context, email string) (IdentifyResult, error)

Identify is the first step of identifier-first sign-in. It never reveals whether an account exists.

func (*Service) Invitation

func (s *Service) Invitation(ctx context.Context, token string) (InvitationView, error)

Invitation describes an invitation for its link.

func (*Service) LeaveWorkspace

func (s *Service) LeaveWorkspace(ctx context.Context) error

LeaveWorkspace removes the caller from the current workspace. The last Owner can't leave. API keys and agents the person created there are revoked, since a key never outlives its creator's access.

func (*Service) MarkRecoveryCodesSaved

func (s *Service) MarkRecoveryCodesSaved(ctx context.Context) error

MarkRecoveryCodesSaved records "I have saved these codes".

func (*Service) Me

func (s *Service) Me(ctx context.Context) (Me, error)

Me returns the signed-in person, their workspaces and instance details.

func (*Service) NextPath

func (s *Service) NextPath(ctx context.Context, u store.User) string

NextPath is where a person goes after signing in.

func (*Service) Overview

func (s *Service) Overview(ctx context.Context) (AccountOverview, error)

Overview returns everything the Account & security screen shows.

func (*Service) PasskeySignIn

func (s *Service) PasskeySignIn(ctx context.Context, challenge string, credential json.RawMessage, remember bool) (SignInResult, *http.Cookie, error)

PasskeySignIn verifies a discoverable passkey and signs the person in.

func (*Service) PasswordSignIn

func (s *Service) PasswordSignIn(ctx context.Context, email, password string, remember bool) (SignInResult, *http.Cookie, error)

PasswordSignIn checks a password and either signs in or asks for a second factor.

func (*Service) RegenerateRecoveryCodes

func (s *Service) RegenerateRecoveryCodes(ctx context.Context) (RecoveryCodes, error)

RegenerateRecoveryCodes replaces every recovery code.

func (*Service) RemoveAvatar

func (s *Service) RemoveAvatar(ctx context.Context) error

RemoveAvatar deletes the profile photo; initials show instead.

func (*Service) RemovePasskey

func (s *Service) RemovePasskey(ctx context.Context, id uuid.UUID) error

RemovePasskey deletes a passkey unless it is the last way to sign in, or the last second factor while two-factor is required.

func (*Service) RenamePasskey

func (s *Service) RenamePasskey(ctx context.Context, id uuid.UUID, name string) error

func (*Service) RequestEmailChange

RequestEmailChange sends a verification link to the new address; the change applies when the person opens it. An account an SSO provider manages keeps its email at a domain the provider enforces, and an account without a password confirms the change with a recent sign-in.

func (*Service) RequestNewInvite

func (s *Service) RequestNewInvite(ctx context.Context, token string) (InvitationRequestResult, error)

RequestNewInvite asks the inviter for a new invitation: for an expired one, or for the signed-in email when the invitation was for another. One request per invitation per day.

func (*Service) RequestPasswordReset

func (s *Service) RequestPasswordReset(ctx context.Context, email string) (PasswordResetRequest, error)

RequestPasswordReset emails a reset link (when a System-stream provider exists) and explains the alternatives otherwise.

func (*Service) ResetPassword

func (s *Service) ResetPassword(ctx context.Context, token, password string) (PasswordResetDone, error)

ResetPassword sets a new password with a one-time link. Every session is signed out and a sign-in lockout is cleared; the next sign-in still asks for the second factor.

func (*Service) RevokeOtherSessions

func (s *Service) RevokeOtherSessions(ctx context.Context) (AccountSessionsRevoked, error)

RevokeOtherSessions signs out every session except this one.

func (*Service) RevokeSession

func (s *Service) RevokeSession(ctx context.Context, id uuid.UUID) error

RevokeSession signs one other session out.

func (*Service) SaveInstanceBasics

func (s *Service) SaveInstanceBasics(ctx context.Context, in InstanceBasics) error

SaveInstanceBasics stores the instance name, public URL, timezone and update check, and marks the setup step done.

func (*Service) Sessions

func (s *Service) Sessions(ctx context.Context) (AccountSessionList, error)

Sessions lists the person's active sessions, the current one first.

func (*Service) SetAvatar

func (s *Service) SetAvatar(ctx context.Context, data []byte) (AccountProfile, error)

SetAvatar stores a profile photo. It is cropped to a square, scaled to 256 px and re-encoded as PNG, which also drops metadata such as location.

func (*Service) Setup

func (s *Service) Setup(ctx context.Context) (SetupState, error)

Setup returns the setup steps for the signed-in person.

func (*Service) SignOut

func (s *Service) SignOut(ctx context.Context) http.Cookie

SignOut revokes the current session.

func (*Service) TwoFactor

func (s *Service) TwoFactor(ctx context.Context, challenge, method, code string) (SignInResult, *http.Cookie, error)

TwoFactor completes a sign-in with an authenticator code or a recovery code.

func (*Service) TwoFactorPasskey

func (s *Service) TwoFactorPasskey(ctx context.Context, challenge, passkeyChallenge string, credential json.RawMessage) (SignInResult, *http.Cookie, error)

TwoFactorPasskey completes a password sign-in with a passkey.

func (*Service) UnlinkIdentity

func (s *Service) UnlinkIdentity(ctx context.Context, id uuid.UUID) error

UnlinkIdentity removes a social or SSO sign-in, unless it is the last way to sign in or the organization manages it.

func (*Service) UpdateProfile

func (s *Service) UpdateProfile(ctx context.Context, in AccountProfileInput) (AccountProfile, error)

UpdateProfile changes the name and timezone.

func (*Service) WorkspaceMe

func (s *Service) WorkspaceMe(ctx context.Context) (WorkspaceMe, error)

WorkspaceMe returns the caller's view of the current workspace.

type SetupInstance

type SetupInstance struct {
	Name        string `json:"name"`
	PublicURL   string `json:"publicUrl"`
	Timezone    string `json:"timezone"`
	UpdateCheck bool   `json:"updateCheck"`
	Confirmed   bool   `json:"confirmed"`
	Version     string `json:"version"`
	// PublicURLLocked: the server pins the public URL
	// (http.public_url_locked); PublicURL is the configured address.
	PublicURLLocked bool `json:"publicUrlLocked"`
	// UpdateCheckAllowed is false when the server configuration turns the
	// update check off (updates.check = false).
	UpdateCheckAllowed bool `json:"updateCheckAllowed"`
}

SetupInstance is the instance basics step.

type SetupPassword

type SetupPassword struct {
	MustChange    bool `json:"mustChange"`
	MinLength     int  `json:"minLength"`
	BreachedCheck bool `json:"breachedCheck"`
}

SetupPassword is the temporary-password step.

type SetupRecoveryCodes

type SetupRecoveryCodes struct {
	Remaining int        `json:"remaining"`
	SavedAt   *time.Time `json:"savedAt,omitempty"`
}

SetupRecoveryCodes is the recovery codes step.

type SetupSecondFactor

type SetupSecondFactor struct {
	TOTP     bool     `json:"totp"`
	Passkeys []string `json:"passkeys" doc:"Names of the passkeys added"`
	Required bool     `json:"required"`
	Reason   string   `json:"reason,omitempty"`
	// GraceUntil is set while a required second factor can still wait.
	GraceUntil *time.Time `json:"graceUntil,omitempty"`
}

SetupSecondFactor is the passkey or authenticator step.

type SetupState

type SetupState struct {
	// Mode: instance (first Owner), account (personal steps only) or done.
	Mode    string      `json:"mode" enum:"instance,account,done"`
	Email   string      `json:"email"`
	Name    string      `json:"name"`
	Steps   []SetupStep `json:"steps"`
	Current string      `json:"current" doc:"Key of the first unfinished step"`
	// Next is where to go when Mode is done.
	Next          string             `json:"next,omitempty"`
	Password      SetupPassword      `json:"password"`
	SecondFactor  SetupSecondFactor  `json:"secondFactor"`
	RecoveryCodes SetupRecoveryCodes `json:"recoveryCodes"`
	Instance      SetupInstance      `json:"instance"`
	Workspace     *CreatedWorkspace  `json:"workspace,omitempty"`
}

SetupState drives /setup: the first sign-in of the install Owner (A5 §5.5), or the steps anyone else must finish before using the app (replace a temporary password, add a required second factor).

type SetupStep

type SetupStep struct {
	Key   string `json:"key" enum:"password,second_factor,recovery_codes,instance,workspace,provider"`
	Label string `json:"label"`
	Done  bool   `json:"done"`
}

SetupStep is one step of the stepper.

type ShellHostRepute

type ShellHostRepute struct {
	Status     string     `json:"status" enum:"connected,revoked,expired,limit_reached,error"`
	TeamName   string     `json:"teamName"`
	LastSyncAt *time.Time `json:"lastSyncAt,omitempty"`
}

ShellHostRepute summarizes the HostRepute connection for the sidebar.

type SignInResult

type SignInResult struct {
	Status string `json:"status" enum:"signed_in,two_factor"`
	// Challenge continues a two-factor sign-in (opaque, single use, 10 minutes).
	Challenge string   `json:"challenge,omitempty"`
	Methods   []string `json:"methods,omitempty" doc:"Second factors available: totp, passkey, recovery"`
	// PasskeyHint names the person's most recently used passkey for the
	// "Confirm with your passkey" step ("MacBook Pro · Touch ID").
	PasskeyHint string `json:"passkeyHint,omitempty"`
	Email       string `json:"email"`
	// Next is where the web app should go after signing in.
	Next string `json:"next,omitempty"`
	// RecoveryCodesLeft is set when a recovery code was used, and with the
	// two-factor step ("Each code works once. 7 of 10 remain.").
	RecoveryCodesLeft *int `json:"recoveryCodesLeft,omitempty"`
	// RecoveryCodesTotal is how many codes the last set had.
	RecoveryCodesTotal *int `json:"recoveryCodesTotal,omitempty"`
}

SignInResult is returned by every sign-in step.

type TOTPSetup

type TOTPSetup struct {
	Secret    string `json:"secret" doc:"Base32 secret grouped by four for manual entry"`
	URL       string `json:"url" doc:"otpauth:// URL for the QR code"`
	Challenge string `json:"challenge" doc:"Pass back with the first code to confirm"`
	Account   string `json:"account"`
	Issuer    string `json:"issuer"`
}

TOTPSetup is the secret shown while setting up an authenticator app.

type URLCheck

type URLCheck struct {
	// URL is the address checked (empty in checks kept before it was recorded).
	URL       string    `json:"url,omitempty"`
	CheckedAt time.Time `json:"checkedAt"`
	DNS       CheckLine `json:"dns"`
	TLS       CheckLine `json:"tls"`
	Reachable CheckLine `json:"reachable"`
}

URLCheck reports whether the public URL resolves, has valid TLS and answers.

func (URLCheck) In

func (c URLCheck) In(l i18n.Lang) URLCheck

In writes the check's lines in a reader's language, for the API: Instance admin and the integrations hub store the check and read it later.

type WorkspaceMe

type WorkspaceMe struct {
	Workspace   MeWorkspace `json:"workspace"`
	Timezone    string      `json:"timezone"`
	ActorType   string      `json:"actorType" enum:"user,api_key,mcp_agent"`
	Permissions []string    `json:"permissions"`
	Scope       authz.Scope `json:"scope"`
	// Unread is the number of unread notifications in this workspace.
	Unread int64 `json:"unread"`
	// HostRepute is the sidebar status line ("HostRepute connected · Acme Inc · synced 4 min ago").
	HostRepute *ShellHostRepute `json:"hostRepute,omitempty"`
	// HiddenSections are the sections the workspace hides from the sidebar,
	// the rail, the tab bar and the More sheet (Settings › General).
	HiddenSections []string `json:"hiddenSections" enum:"transactional,grow,earn"`
}

WorkspaceMe is GET /workspaces/{workspace}/me: the caller's role and permissions there, and the bits of workspace state the app shell shows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL