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
- func CreateResetToken(ctx context.Context, q *store.Queries, userID uuid.UUID, source string, ...) (string, time.Time, error)
- func Register(h huma.API, s *Service)
- func ResetLink(publicURL, token string) string
- type AccountAvatarInput
- type AccountEmailChangeInput
- type AccountEmailChangeStarted
- type AccountEmailChanged
- type AccountIdentity
- type AccountOverview
- type AccountPasskey
- type AccountPassword
- type AccountPendingEmail
- type AccountProfile
- type AccountProfileInput
- type AccountSession
- type AccountSessionList
- type AccountSessionPolicy
- type AccountSessionsRevoked
- type AccountTwoFactor
- type AccountWorkspace
- type AvatarImage
- type CheckLine
- type CreatedWorkspace
- type Device
- type ExternalIdentity
- type ExternalResult
- type ExternalSignIn
- type IdentifyResult
- type InstanceBasics
- type InvitationAcceptInput
- type InvitationAccepted
- type InvitationAgency
- type InvitationPasswordPolicy
- type InvitationRequestResult
- type InvitationTwoFactor
- type InvitationView
- type Me
- type MeInstance
- type MeUser
- type MeWorkspace
- type PasskeyOptions
- type PasswordResetDone
- type PasswordResetInfo
- type PasswordResetRequest
- type PathID
- type PathToken
- type RecoveryCodes
- type SSOStart
- type Service
- func (s *Service) AcceptInvitation(ctx context.Context, token string, in InvitationAcceptInput) (InvitationAccepted, *http.Cookie, error)
- func (s *Service) AcceptInvitationExternal(ctx context.Context, token string, id ExternalIdentity) (ExternalResult, error)
- func (s *Service) Avatar(ctx context.Context, userID uuid.UUID) (*AvatarImage, error)
- func (s *Service) BeginPasskeyRegistration(ctx context.Context) (PasskeyOptions, error)
- func (s *Service) BeginPasskeySignIn(ctx context.Context) (PasskeyOptions, error)
- func (s *Service) BeginTOTP(ctx context.Context) (TOTPSetup, error)
- func (s *Service) BeginTwoFactorPasskey(ctx context.Context, challenge string) (PasskeyOptions, error)
- func (s *Service) CancelEmailChange(ctx context.Context) error
- func (s *Service) ChangePassword(ctx context.Context, current, next string) error
- func (s *Service) CheckPasswordReset(ctx context.Context, token string) (PasswordResetInfo, error)
- func (s *Service) CheckPublicURL(ctx context.Context, raw string) (URLCheck, error)
- func (s *Service) CompleteExternalSignIn(ctx context.Context, in ExternalSignIn) (ExternalResult, error)
- func (s *Service) CompleteSetup(ctx context.Context) error
- func (s *Service) ConfirmEmailChange(ctx context.Context, token string) (AccountEmailChanged, error)
- func (s *Service) ConfirmTOTP(ctx context.Context, challenge, code string) (RecoveryCodes, error)
- func (s *Service) CreateWorkspace(ctx context.Context, name, timezone string) (CreatedWorkspace, error)
- func (s *Service) FinishPasskeyRegistration(ctx context.Context, challenge string, credential json.RawMessage, name string) (AccountPasskey, error)
- func (s *Service) Identify(ctx context.Context, email string) (IdentifyResult, error)
- func (s *Service) Invitation(ctx context.Context, token string) (InvitationView, error)
- func (s *Service) LeaveWorkspace(ctx context.Context) error
- func (s *Service) MarkRecoveryCodesSaved(ctx context.Context) error
- func (s *Service) Me(ctx context.Context) (Me, error)
- func (s *Service) NextPath(ctx context.Context, u store.User) string
- func (s *Service) Overview(ctx context.Context) (AccountOverview, error)
- func (s *Service) PasskeySignIn(ctx context.Context, challenge string, credential json.RawMessage, ...) (SignInResult, *http.Cookie, error)
- func (s *Service) PasswordSignIn(ctx context.Context, email, password string, remember bool) (SignInResult, *http.Cookie, error)
- func (s *Service) RegenerateRecoveryCodes(ctx context.Context) (RecoveryCodes, error)
- func (s *Service) RemoveAvatar(ctx context.Context) error
- func (s *Service) RemovePasskey(ctx context.Context, id uuid.UUID) error
- func (s *Service) RenamePasskey(ctx context.Context, id uuid.UUID, name string) error
- func (s *Service) RequestEmailChange(ctx context.Context, in AccountEmailChangeInput) (AccountEmailChangeStarted, error)
- func (s *Service) RequestNewInvite(ctx context.Context, token string) (InvitationRequestResult, error)
- func (s *Service) RequestPasswordReset(ctx context.Context, email string) (PasswordResetRequest, error)
- func (s *Service) ResetPassword(ctx context.Context, token, password string) (PasswordResetDone, error)
- func (s *Service) RevokeOtherSessions(ctx context.Context) (AccountSessionsRevoked, error)
- func (s *Service) RevokeSession(ctx context.Context, id uuid.UUID) error
- func (s *Service) SaveInstanceBasics(ctx context.Context, in InstanceBasics) error
- func (s *Service) Sessions(ctx context.Context) (AccountSessionList, error)
- func (s *Service) SetAvatar(ctx context.Context, data []byte) (AccountProfile, error)
- func (s *Service) Setup(ctx context.Context) (SetupState, error)
- func (s *Service) SignOut(ctx context.Context) http.Cookie
- func (s *Service) TwoFactor(ctx context.Context, challenge, method, code string) (SignInResult, *http.Cookie, error)
- func (s *Service) TwoFactorPasskey(ctx context.Context, challenge, passkeyChallenge string, ...) (SignInResult, *http.Cookie, error)
- func (s *Service) UnlinkIdentity(ctx context.Context, id uuid.UUID) error
- func (s *Service) UpdateProfile(ctx context.Context, in AccountProfileInput) (AccountProfile, error)
- func (s *Service) WorkspaceMe(ctx context.Context) (WorkspaceMe, error)
- type SetupInstance
- type SetupPassword
- type SetupRecoveryCodes
- type SetupSecondFactor
- type SetupState
- type SetupStep
- type ShellHostRepute
- type SignInResult
- type TOTPSetup
- type URLCheck
- type WorkspaceMe
Constants ¶
const ResetTTL = 15 * time.Minute
ResetTTL is how long a password reset link works.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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 ¶
MarshalJSON adds the kept message ("i18n") to the line.
func (*CheckLine) UnmarshalJSON ¶
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 ¶
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"`
}
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 ¶
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 ¶
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 ¶
CancelEmailChange drops a pending email change.
func (*Service) ChangePassword ¶
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 ¶
CheckPasswordReset tells whether a reset link still works.
func (*Service) CheckPublicURL ¶
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 ¶
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 ¶
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 ¶
Identify is the first step of identifier-first sign-in. It never reveals whether an account exists.
func (*Service) Invitation ¶
Invitation describes an invitation for its link.
func (*Service) LeaveWorkspace ¶
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 ¶
MarkRecoveryCodesSaved records "I have saved these codes".
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 ¶
RemoveAvatar deletes the profile photo; initials show instead.
func (*Service) RemovePasskey ¶
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 (*Service) RequestEmailChange ¶
func (s *Service) RequestEmailChange(ctx context.Context, in AccountEmailChangeInput) (AccountEmailChangeStarted, error)
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 ¶
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 ¶
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) 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 ¶
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.
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.