accounts

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 42 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"`
}

CheckLine is one row of the public URL check.

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
	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"`
}

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"`
}

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 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"`
	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"`
}

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"`
}

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"`
}

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: the invitation link proved the invitee owns the invited email, and the identity's email must be the same. New people get an account without a password; the identity is linked either way.

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).

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.

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.

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"`
}

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 {
	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"`
}

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