team

package
v1.5.0 Latest Latest
Warning

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

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

Documentation

Overview

Package team manages the people of a workspace (A5 §3.5, §5.8): members, invitations, role and scope changes, deactivation and removal. The last Owner can't be removed or demoted, and nobody can grant a permission they don't hold.

Index

Constants

View Source
const CodeNoSystemProvider = "no_system_provider"

CodeNoSystemProvider marks invite emails that couldn't be sent because no provider is assigned to the System stream; the response carries the links.

View Source
const DefaultInviteDays = 7

DefaultInviteDays is how long an invitation link works unless the inviter picks another expiry.

Variables

This section is empty.

Functions

func Register

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

Register adds the team operations.

Types

type InvitationPathInput

type InvitationPathInput struct {
	api.WorkspaceInput
	InvitationID string `path:"invitationId" format:"uuid"`
}

InvitationPathInput is a path or query input shared by several operations.

type ListFilter

type ListFilter struct {
	Query  string
	Role   string // role id or key
	Status string // active | deactivated
	TwoFA  string // on | off | idp | required
}

ListFilter narrows the members list.

type MemberPathInput

type MemberPathInput struct {
	api.WorkspaceInput
	MemberID string `path:"memberId" format:"uuid"`
}

MemberPathInput is a path or query input shared by several operations.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Box   *secrets.Box
	// Mail sends invitations through the System stream; mailer.ErrNoSystemProvider
	// switches to copyable links.
	Mail mailer.Sender
	// PublicURL returns the externally reachable base URL for invite links.
	PublicURL func(context.Context) string
	Now       func() time.Time
}

func (*Service) Bulk

Bulk changes roles, requires two-factor now or deactivates several members in one transaction: all of them or none.

func (*Service) ChangeRole

func (s *Service) ChangeRole(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID, in TeamMemberChangeInput) error

ChangeRole gives a member another role and scope.

func (*Service) Deactivate

Deactivate keeps the member's history, closes the workspace to them at once, signs them out unless their sessions serve other workspaces too (sessionsShared) and keeps or revokes the API keys they created.

func (*Service) Get

func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) (TeamMemberDetail, error)

Get returns the member detail.

func (*Service) Invitations

func (s *Service) Invitations(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInvitationList, error)

Invitations lists pending invitations.

func (*Service) Invite

Invite creates one invitation per email, then emails them through the System stream. Without a System provider the links are returned instead.

Link returns the link of a pending invitation (the emailed link stays valid).

func (*Service) List

List returns the members of the workspace.

func (*Service) Options

Options returns what the invite dialog needs.

func (*Service) Reactivate

func (s *Service) Reactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) error

Reactivate restores a deactivated member. A deactivated account (instance level) needs an instance admin.

func (*Service) Remove

func (s *Service) Remove(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) error

Remove deletes the membership. The audit log keeps naming the person; the API keys they created in this workspace are revoked.

func (*Service) Resend

Resend emails a pending invitation again and restarts its expiry.

func (*Service) Revoke

func (s *Service) Revoke(ctx context.Context, ws *store.Workspace, id uuid.UUID) error

Revoke cancels a pending invitation; its link stops working.

func (*Service) SignOut

func (s *Service) SignOut(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) (TeamSignOutResult, error)

SignOut ends every session of the member. When their sessions serve other workspaces too (sessionsShared), only an instance admin can; the member can always sign themselves out.

type TeamBulkInput

type TeamBulkInput struct {
	MemberIDs  []string `json:"memberIds" minItems:"1" maxItems:"200"`
	Action     string   `json:"action" enum:"change_role,require_2fa,deactivate"`
	RoleID     string   `json:"roleId,omitempty" doc:"For change_role"`
	RevokeKeys bool     `json:"revokeKeys,omitempty" doc:"For deactivate"`
	Reason     string   `json:"reason,omitempty" maxLength:"500"`
}

TeamBulkInput applies one action to several members.

type TeamBulkResult

type TeamBulkResult struct {
	Changed int `json:"changed"`
	// Skipped names members already in the requested state.
	Skipped []string `json:"skipped"`
}

TeamBulkResult reports how many members changed.

type TeamCounts

type TeamCounts struct {
	Members     int `json:"members"`
	Active      int `json:"active"`
	Deactivated int `json:"deactivated"`
	Invited     int `json:"invited"`
}

TeamCounts feeds "6 members · 1 invited".

type TeamCreatedInvitation

type TeamCreatedInvitation struct {
	ID    string `json:"id"`
	Email string `json:"email"`
	// Link is the invitation URL. It is shown to the inviter so it can be
	// shared when email isn't available.
	Link    string `json:"link"`
	Emailed bool   `json:"emailed"`
}

TeamCreatedInvitation is one created invitation with its link.

type TeamDeactivateInput

type TeamDeactivateInput struct {
	// RevokeKeys revokes the API keys and agents the member created; false keeps them working.
	RevokeKeys bool   `json:"revokeKeys,omitempty"`
	Reason     string `json:"reason,omitempty" maxLength:"500" doc:"Recorded in the audit log"`
}

TeamDeactivateInput deactivates a member.

type TeamDeactivateResult

type TeamDeactivateResult struct {
	SessionsRevoked int64    `json:"sessionsRevoked"`
	KeysRevoked     []string `json:"keysRevoked"`
}

TeamDeactivateResult says what happened.

type TeamEffectivePermission

type TeamEffectivePermission struct {
	Key       string `json:"key"`
	Group     string `json:"group"`
	Label     string `json:"label"`
	Sensitive bool   `json:"sensitive"`
	Granted   bool   `json:"granted"`
	// Source is "Role · Content Writer", "SSO group mapping · Marketing" or "not granted".
	Source string `json:"source"`
	// IncludedBy is the permission that brings this one in ("campaigns:edit").
	IncludedBy string `json:"includedBy,omitempty"`
	// Scope is "all lists", a list label, or "" when not granted.
	Scope string `json:"scope"`
}

TeamEffectivePermission is one row of the member detail's permission table.

type TeamInvitation

type TeamInvitation struct {
	ID        string              `json:"id"`
	Email     string              `json:"email"`
	Role      TeamRoleRef         `json:"role"`
	Scope     access.ScopeSummary `json:"scope"`
	Message   string              `json:"message"`
	InvitedBy string              `json:"invitedBy"`
	// SentVia is the provider that delivered the email ("Postmark"); empty
	// when the invite was only shared as a link.
	SentVia    string     `json:"sentVia"`
	CreatedAt  time.Time  `json:"createdAt"`
	LastSentAt *time.Time `json:"lastSentAt,omitempty"`
	ExpiresAt  time.Time  `json:"expiresAt"`
	Expired    bool       `json:"expired"`
}

TeamInvitation is a pending invitation.

type TeamInvitationList

type TeamInvitationList struct {
	Items []TeamInvitation `json:"items"`
	// DefaultDays is the default expiry ("Links work for 7 days by default").
	DefaultDays int `json:"defaultDays"`
	// JIT describes SSO domains whose people can join on their own.
	JIT []TeamJITHint `json:"jit"`
	// CanInvite reflects team:invite (resend, copy link and revoke are hidden without it).
	CanInvite bool `json:"canInvite"`
}

TeamInvitationList is the pending invitations card.

type TeamInviteInput

type TeamInviteInput struct {
	Emails        []string             `json:"emails" minItems:"1" maxItems:"50"`
	RoleID        string               `json:"roleId" format:"uuid"`
	Scope         *access.ScopeRequest `json:"scope,omitempty"`
	ExpiresInDays int                  `json:"expiresInDays,omitempty" minimum:"1" maximum:"30" doc:"Defaults to 7"`
	Message       string               `json:"message,omitempty" maxLength:"1000"`
	// SendEmail false only creates the links (the "copy links" fallback).
	SendEmail *bool `json:"sendEmail,omitempty"`
	// Language is the invitation email's and the page's; the instance
	// default when omitted. Once they sign in, members pick their own.
	Language string `json:"language,omitempty" enum:"en,de,es,fr,vi"`
}

TeamInviteInput creates invitations.

type TeamInviteLink struct {
	Link      string    `json:"link"`
	ExpiresAt time.Time `json:"expiresAt"`
}

TeamInviteLink is a copyable invitation link.

type TeamInviteOptions

type TeamInviteOptions struct {
	Workspace string           `json:"workspace"`
	Roles     []TeamInviteRole `json:"roles"`
	// DefaultRoleID is Editor when grantable, otherwise the broadest grantable role.
	DefaultRoleID string              `json:"defaultRoleId"`
	Lists         []access.ScopedList `json:"lists"`
	SenderDomains []string            `json:"senderDomains"`
	JIT           []TeamJITHint       `json:"jit"`
	// SystemProvider names the provider of the System stream ("Postmark").
	// Empty when invitations can't be emailed yet; the dialog then offers links.
	SystemProvider string `json:"systemProvider"`
	CanEmail       bool   `json:"canEmail"`
	DefaultDays    int    `json:"defaultDays"`
	ExpiryOptions  []int  `json:"expiryOptions"`
	// SignInSummary is "Invitees pick a password or continue with Google, Microsoft or GitHub."
	SignInSummary string `json:"signInSummary"`
	// Languages an invitation can be written in, and the instance default
	// the dialog starts on.
	Languages       []applang.LanguageOption `json:"languages,omitempty"`
	DefaultLanguage string                   `json:"defaultLanguage,omitempty" example:"en"`
}

TeamInviteOptions feeds the invite dialog.

type TeamInviteResult

type TeamInviteResult struct {
	Invitations []TeamCreatedInvitation `json:"invitations"`
	Emailed     bool                    `json:"emailed"`
	// Fallback is "no_system_provider" when email couldn't be sent.
	Fallback string `json:"fallback,omitempty"`
	SentVia  string `json:"sentVia,omitempty"`
}

TeamInviteResult reports what was created and whether email went out.

type TeamInviteRole

type TeamInviteRole struct {
	ID        string `json:"id"`
	Key       string `json:"key"`
	Name      string `json:"name"`
	Builtin   bool   `json:"builtin"`
	Sensitive bool   `json:"sensitive" doc:"Holders need two-factor"`
	// Grantable is false when the inviter doesn't hold every permission of
	// the role (or it is the Owner role, which only a transfer gives).
	Grantable bool   `json:"grantable"`
	Reason    string `json:"reason,omitempty"`
	// Hint is "Editors can send; two-factor becomes required (7-day grace)."
	Hint string `json:"hint"`
}

TeamInviteRole is a role offered in the invite dialog.

type TeamJITHint

type TeamJITHint struct {
	Domain   string `json:"domain"`
	Provider string `json:"provider"`
	Preset   string `json:"preset"`
	RoleName string `json:"roleName"`
}

TeamJITHint is "acme.io users can also join automatically with Google Workspace".

type TeamMember

type TeamMember struct {
	ID          string              `json:"id" doc:"Membership id"`
	UserID      string              `json:"userId"`
	Name        string              `json:"name"`
	Email       string              `json:"email"`
	AvatarColor string              `json:"avatarColor"`
	Role        TeamRoleRef         `json:"role"`
	Scope       access.ScopeSummary `json:"scope"`
	// Notes follow the role: "instance admin", "break-glass".
	Notes        []string                    `json:"notes"`
	SignIn       []access.MemberSignInMethod `json:"signIn"`
	TwoFA        access.MemberTwoFA          `json:"twoFA"`
	LastActiveAt *time.Time                  `json:"lastActiveAt,omitempty"`
	Status       string                      `json:"status" enum:"active,deactivated"`
	// Deactivated members of the instance (not only of this workspace).
	AccountDeactivated bool       `json:"accountDeactivated"`
	DeactivatedAt      *time.Time `json:"deactivatedAt,omitempty"`
	JoinedAt           time.Time  `json:"joinedAt"`
	// Source is where the membership came from: invite, sso_jit, sso_group, install, transfer, self.
	Source string `json:"source"`
	// You is true for the signed-in person.
	You bool `json:"you"`
	// LastOwner is true when this is the only active Owner.
	LastOwner bool `json:"lastOwner"`
}

TeamMember is one row of the members list.

type TeamMemberAPIKey

type TeamMemberAPIKey struct {
	ID          string   `json:"id"`
	Kind        string   `json:"kind" enum:"api_key,mcp_agent"`
	Name        string   `json:"name"`
	Masked      string   `json:"masked"`
	Permissions []string `json:"permissions"`
	// Scope is "Weekly Digest" or "all lists".
	Scope      string     `json:"scope"`
	Status     string     `json:"status" enum:"active,expired,revoked"`
	LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
}

TeamMemberAPIKey is a key or agent the member created.

type TeamMemberActivity

type TeamMemberActivity struct {
	ID         string    `json:"id"`
	OccurredAt time.Time `json:"occurredAt"`
	Action     string    `json:"action"`
	Target     string    `json:"target"`
	Result     string    `json:"result" enum:"allowed,denied,error"`
	Reason     string    `json:"reason,omitempty"`
}

TeamMemberActivity is one recent audit entry by the member.

type TeamMemberApproval

type TeamMemberApproval struct {
	Campaign   string    `json:"campaign"`
	CampaignID string    `json:"campaignId,omitempty"`
	Status     string    `json:"status" doc:"approve, request_changes, reject (given) or the request status (requested)"`
	At         time.Time `json:"at"`
}

TeamMemberApproval is an approval the member gave or requested.

type TeamMemberChangeInput

type TeamMemberChangeInput struct {
	RoleID string               `json:"roleId" format:"uuid"`
	Scope  *access.ScopeRequest `json:"scope,omitempty"`
}

TeamMemberChangeInput changes a member's role and scope.

type TeamMemberDetail

type TeamMemberDetail struct {
	Member      TeamMember                `json:"member"`
	Permissions []TeamEffectivePermission `json:"permissions"`
	Groups      []string                  `json:"groups"`
	APIKeys     []TeamMemberAPIKey        `json:"apiKeys"`
	// KeysNote explains an empty list ("None. This role can't create API keys.").
	KeysNote           string               `json:"keysNote,omitempty"`
	ApprovalsGiven     []TeamMemberApproval `json:"approvalsGiven"`
	ApprovalsRequested []TeamMemberApproval `json:"approvalsRequested"`
	CanApprove         bool                 `json:"canApprove"`
	Sessions           int64                `json:"sessions"`
	// SessionsShared: the person also belongs to other workspaces or is an
	// instance admin, so their sessions serve more than this workspace and
	// deactivating them here leaves those sessions alone.
	SessionsShared bool `json:"sessionsShared"`
	// SignOutReason says why the caller can't end the person's sessions from
	// here (only an instance admin can); empty when they can.
	SignOutReason string `json:"signOutReason,omitempty"`
	// ScheduledCampaigns counts scheduled sends the member created (they keep their schedule).
	ScheduledCampaigns int64 `json:"scheduledCampaigns"`
	// SSODomain is the email domain used with SSO ("acme.io").
	SSODomain string `json:"ssoDomain,omitempty"`
	// SignInMethods is every way the member signs in, linked SSO and social
	// identities included (the list shows only the primary ones).
	SignInMethods []access.MemberSignInMethod `json:"signInMethods"`
	Activity      []TeamMemberActivity        `json:"activity"`
	CanManage     bool                        `json:"canManage"`
	// Helpers are members who hold team:manage.
	Helpers []string `json:"helpers"`
}

TeamMemberDetail is the member page (A5 §5.8 member detail).

type TeamMemberList

type TeamMemberList struct {
	Items  []TeamMember `json:"items"`
	Counts TeamCounts   `json:"counts"`
	// Roles available in the role filter and the bulk role select.
	Roles []TeamRoleRef `json:"roles"`
	// CanInvite / CanManage reflect the caller's team:invite and team:manage.
	CanInvite bool `json:"canInvite"`
	CanManage bool `json:"canManage"`
	// Reason explains read-only access ("Your role can't invite people…").
	Reason string `json:"reason,omitempty"`
	// Helpers are members who hold team:manage.
	Helpers []string `json:"helpers"`
}

TeamMemberList is the members list with the caller's abilities.

type TeamResendResult

type TeamResendResult struct {
	Emailed   bool      `json:"emailed"`
	SentVia   string    `json:"sentVia,omitempty"`
	Link      string    `json:"link"`
	ExpiresAt time.Time `json:"expiresAt"`
	Fallback  string    `json:"fallback,omitempty"`
}

TeamResendResult reports a resend.

type TeamRoleRef

type TeamRoleRef struct {
	ID      string `json:"id"`
	Key     string `json:"key"`
	Name    string `json:"name"`
	Builtin bool   `json:"builtin"`
}

TeamRoleRef names a member's role.

type TeamSignOutResult

type TeamSignOutResult struct {
	SessionsRevoked int64 `json:"sessionsRevoked"`
}

TeamSignOutResult reports a forced sign-out.

Jump to

Keyboard shortcuts

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