Files
Enterprise-Knowledge-Base/frontend/src/api/tenant/invitations.ts
T
lyingbug 3611a8607d feat(rbac): add multi-use share-link invitations for invite_only mode (#1504)
* feat(rbac): add multi-use share-link invitations for invite_only mode

When the auth.registration_mode toggle flips to invite_only, the public
/auth/register endpoint returns 403 — but until now there was no
channel for unregistered users to actually join a tenant. The existing
invitation table required a registered invitee, so new emails could
not enter the system at all.

This change introduces a share-link model:

- Owner generates a multi-use registration link with a per-tenant role
- Recipient opens the link, registers with their own email, and is
  added to the tenant on the same request
- Token is stored in plaintext (not hashed) so the management UI can
  re-display the URL on demand without a "copy now or revoke" trap.
  Threat model is bounded by 7-day TTL, revocability, and the fact
  that all the link grants is membership in one tenant.
- accepted_count tracks how many users joined through the link so the
  Owner can tell whether a link is fresh or has already been spread

Per-user invitations (registered email -> in-app inbox accept) are
unchanged. Share-link rows use empty invitee_user_id as discriminator;
the partial unique index on (tenant_id, invitee_user_id) was relaxed
to skip empty values so multiple share links can coexist per tenant.

Frontend reuses Login.vue for /register?token=xxx instead of a
parallel page, and adds icon-only revoke / remove actions plus a
distinct "active" status tag for share-link rows.

Migration 000054 adds the token column, the accepted_count column,
and the relaxed pending unique index in a single step.

* feat(auth): update invitation token handling and add rate limiting

- Refactor the invitation token retrieval to use POST instead of GET, enhancing security by preventing the plaintext token from appearing in logs and browser history.
- Update the API endpoint from `/auth/invitations/:token` to `/auth/invitations/lookup` to reflect the new method.
- Introduce a rate limiter for unauthenticated share-link endpoints to mitigate brute-force attacks and abuse, ensuring a maximum of 30 requests per minute per IP.
- Adjust the registration flow to maintain user experience while securing the invitation process.
2026-05-27 19:42:01 +08:00

237 lines
7.1 KiB
TypeScript

import { get, post, del } from '@/utils/request'
import type { TenantRole } from '@/api/tenant/members'
// TenantInvitationStatus mirrors internal/types/tenant_invitation.go's
// five-state machine. pending is the only non-terminal state; the rest
// are recorded for the audit trail.
export type TenantInvitationStatus =
| 'pending'
| 'accepted'
| 'declined'
| 'revoked'
| 'expired'
// TenantInvitation is the API projection of a tenant_invitations row,
// hydrated with the inviter / invitee user fields and the tenant name
// when the backend has them. Missing optional fields render as the
// raw id in the UI rather than dropping the row.
export interface TenantInvitation {
id: number
tenant_id: number
tenant_name?: string
invitee_user_id: string
invitee_email?: string
invitee_name?: string
invited_by?: string | null
inviter_email?: string
inviter_name?: string
role: TenantRole
status: TenantInvitationStatus
message?: string
expires_at: string
responded_at?: string | null
created_at: string
// invite_url is set on share-link rows that are still pending. The
// backend re-emits it on every list/get so Owners can copy the
// link on demand without "copy now or revoke" pressure.
invite_url?: string
// is_share_link distinguishes share-link rows (no specific invitee,
// multi-use, copyable URL) from per-user invitations.
is_share_link?: boolean
// accepted_count counts how many users have completed registration
// through this invitation. Surfaced in the management UI for
// share-link rows ("已加入 N 人").
accepted_count?: number
}
export interface ListInvitationsResponse {
success: boolean
data?: {
invitations: TenantInvitation[]
total: number
page?: number
page_size?: number
}
message?: string
}
export interface ListTenantInvitationsParams {
includeTerminal?: boolean
page?: number
page_size?: number
}
function buildTenantInvitationsQuery(options: ListTenantInvitationsParams): string {
const u = new URLSearchParams()
if (options.includeTerminal) u.set('include_terminal', 'true')
if (options.page != null && options.page > 0) u.set('page', String(options.page))
if (options.page_size != null && options.page_size > 0) u.set('page_size', String(options.page_size))
const qs = u.toString()
return qs ? `?${qs}` : ''
}
export interface CreateInvitationRequest {
email: string
role: TenantRole
message?: string
}
export interface CreateInvitationResponse {
success: boolean
data?: TenantInvitation
message?: string
}
export interface SimpleResponse {
success: boolean
message?: string
}
export interface AcceptInvitationResponse {
success: boolean
data?: {
membership: {
tenant_id: number
role: TenantRole
status: string
joined_at: string
}
}
message?: string
}
export interface PendingCountResponse {
success: boolean
data?: { pending_count: number }
message?: string
}
/**
* List invitations for a tenant. Defaults to pending only; pass
* includeTerminal=true to also surface accepted/declined/revoked/
* expired rows for the history view. Supports `page` / `page_size`.
* Backend: GET /api/v1/tenants/:id/invitations (Viewer+).
*/
export async function listTenantInvitations(
tenantId: number,
options: ListTenantInvitationsParams = {},
): Promise<ListInvitationsResponse> {
const qs = buildTenantInvitationsQuery(options)
return (await get(
`/api/v1/tenants/${tenantId}/invitations${qs}`,
)) as unknown as ListInvitationsResponse
}
/**
* Send a new invitation. The invitee will see it in /me/invitations
* and must accept before they actually become a member.
* Backend: POST /api/v1/tenants/:id/invitations (Owner+).
*
* 404 when the email is not a registered user (ask them to register).
* 409 when an existing pending invitation already covers this pair, or
* when the invitee is already an active member.
*/
export async function createInvitation(
tenantId: number,
body: CreateInvitationRequest,
): Promise<CreateInvitationResponse> {
return (await post(
`/api/v1/tenants/${tenantId}/invitations`,
body,
)) as unknown as CreateInvitationResponse
}
/**
* Revoke a still-pending invitation. Already-finalised rows return
* 409; rows from another tenant render as 404 to avoid existence
* leaks across tenants.
* Backend: DELETE /api/v1/tenants/:id/invitations/:inv_id (Owner+).
*/
export async function revokeInvitation(
tenantId: number,
invId: number,
): Promise<SimpleResponse> {
return (await del(
`/api/v1/tenants/${tenantId}/invitations/${invId}`,
)) as unknown as SimpleResponse
}
/**
* List MY invitations. Defaults to pending only — the inbox page
* filters terminal rows by default; pass includeTerminal=true for a
* history view if/when the UI grows one.
* Backend: GET /api/v1/me/invitations (authenticated).
*/
export async function listMyInvitations(
options: { includeTerminal?: boolean } = {},
): Promise<ListInvitationsResponse> {
const qs = options.includeTerminal ? '?include_terminal=true' : ''
return (await get(`/api/v1/me/invitations${qs}`)) as unknown as ListInvitationsResponse
}
/**
* Lightweight pending-count endpoint used by the avatar-row badge
* poller. Separate from the list endpoint so polling doesn't transfer
* the full payload every cycle.
* Backend: GET /api/v1/me/invitations/pending-count (authenticated).
*/
export async function getMyPendingInvitationCount(): Promise<PendingCountResponse> {
return (await get(
`/api/v1/me/invitations/pending-count`,
)) as unknown as PendingCountResponse
}
/**
* Accept one of MY pending invitations. On success the backend also
* creates the tenant_members row in the same flow; the caller should
* then refresh memberships in the auth store.
* Backend: POST /api/v1/me/invitations/:inv_id/accept (authenticated).
*/
export async function acceptInvitation(invId: number): Promise<AcceptInvitationResponse> {
return (await post(
`/api/v1/me/invitations/${invId}/accept`,
)) as unknown as AcceptInvitationResponse
}
/**
* Decline one of MY pending invitations.
* Backend: POST /api/v1/me/invitations/:inv_id/decline (authenticated).
*/
export async function declineInvitation(invId: number): Promise<SimpleResponse> {
return (await post(
`/api/v1/me/invitations/${invId}/decline`,
)) as unknown as SimpleResponse
}
// ---- share-link API ----------------------------------------------------
export interface CreateInviteLinkRequest {
role: TenantRole
message?: string
}
export interface CreateInviteLinkResponse {
success: boolean
data?: TenantInvitation
message?: string
}
/**
* Generate a multi-use share-link invitation for the tenant. The
* returned row carries `invite_url` (composed from the persisted
* plaintext token) which the SPA copies into clipboards. The link
* stays valid until expiry or revocation; revoking is the same DELETE
* as a per-user invitation.
*
* Backend: POST /api/v1/tenants/:id/invite-links (Owner+).
*/
export async function createInviteLink(
tenantId: number,
body: CreateInviteLinkRequest,
): Promise<CreateInviteLinkResponse> {
return (await post(
`/api/v1/tenants/${tenantId}/invite-links`,
body,
)) as unknown as CreateInviteLinkResponse
}