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
- func Register(h huma.API, s *Service)
- type InvitationPathInput
- type ListFilter
- type MemberPathInput
- type Service
- func (s *Service) Bulk(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamBulkInput) (TeamBulkResult, error)
- func (s *Service) ChangeRole(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Deactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamDeactivateResult, error)
- func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamMemberDetail, error)
- func (s *Service) Invitations(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInvitationList, error)
- func (s *Service) Invite(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamInviteResult, error)
- func (s *Service) Link(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamInviteLink, error)
- func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, f ListFilter) (TeamMemberList, error)
- func (s *Service) Options(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInviteOptions, error)
- func (s *Service) Reactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Remove(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Resend(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamResendResult, error)
- func (s *Service) Revoke(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) SignOut(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamSignOutResult, error)
- type TeamBulkInput
- type TeamBulkResult
- type TeamCounts
- type TeamCreatedInvitation
- type TeamDeactivateInput
- type TeamDeactivateResult
- type TeamEffectivePermission
- type TeamInvitation
- type TeamInvitationList
- type TeamInviteInput
- type TeamInviteLink
- type TeamInviteOptions
- type TeamInviteResult
- type TeamInviteRole
- type TeamJITHint
- type TeamMember
- type TeamMemberAPIKey
- type TeamMemberActivity
- type TeamMemberApproval
- type TeamMemberChangeInput
- type TeamMemberDetail
- type TeamMemberList
- type TeamResendResult
- type TeamRoleRef
- type TeamSignOutResult
Constants ¶
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.
const DefaultInviteDays = 7
DefaultInviteDays is how long an invitation link works unless the inviter picks another expiry.
Variables ¶
This section is empty.
Functions ¶
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 ¶
func (s *Service) Bulk(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamBulkInput) (TeamBulkResult, error)
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 ¶
func (s *Service) Deactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID, in TeamDeactivateInput) (TeamDeactivateResult, error)
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 ¶
func (s *Service) Invite(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamInviteInput) (TeamInviteResult, error)
Invite creates one invitation per email, then emails them through the System stream. Without a System provider the links are returned instead.
func (*Service) Link ¶
func (s *Service) Link(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamInviteLink, error)
Link returns the link of a pending invitation (the emailed link stays valid).
func (*Service) List ¶
func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, f ListFilter) (TeamMemberList, error)
List returns the members of the workspace.
func (*Service) Options ¶
func (s *Service) Options(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInviteOptions, error)
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 ¶
func (s *Service) Resend(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamResendResult, error)
Resend emails a pending invitation again and restarts its expiry.
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 ¶
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"`
// 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.