The minimalistic document archiving platform.
feat(admin): add plan entitlements management for users (#1163)
Corentin Thomassetd60250573bdf
diff --git a/apps/papra-client/src/locales/en.dictionary.ts b/apps/papra-client/src/locales/en.dictionary.tsindex ea9681ea..49506737 100644--- a/apps/papra-client/src/locales/en.dictionary.ts+++ b/apps/papra-client/src/locales/en.dictionary.ts@@ -1071,6 +1071,10 @@ export const translations = {'The provided URL is not allowed. Webhook URLs must not point to private or reserved IP addresses.','api-errors.users.still_owns_organizations':'This user still owns one or more organizations. Delete those organizations before deleting the user.',+ 'api-errors.plan_entitlements.already_exists':+ 'This user already has an entitlement of this type.',+ 'api-errors.plan_entitlements.not_found': 'Plan entitlement not found.',+ 'api-errors.plan_entitlements.not_eligible': 'This user is not eligible for this entitlement.','api-errors.users.cannot_delete_self': 'You cannot delete your own account from the admin panel.',// Better auth api errors'api-errors.USER_NOT_FOUND': 'User not found',@@ -1299,6 +1303,33 @@ export const translations = {'admin.user-detail.organizations.table.id': 'ID','admin.user-detail.organizations.table.name': 'Name','admin.user-detail.organizations.table.created': 'Created',+ 'admin.user-detail.plan-entitlements.title': 'Plan entitlements',+ 'admin.user-detail.plan-entitlements.description':+ 'Entitlements that boost the plan of the organizations this user owns',+ 'admin.user-detail.plan-entitlements.empty': 'No plan entitlements',+ 'admin.user-detail.plan-entitlements.table.type': 'Type',+ 'admin.user-detail.plan-entitlements.table.source': 'Source',+ 'admin.user-detail.plan-entitlements.table.granted': 'Granted',+ 'admin.user-detail.plan-entitlements.table.expires': 'Expires',+ 'admin.user-detail.plan-entitlements.never-expires': 'Never',+ 'admin.user-detail.plan-entitlements.expired': 'Expired',+ 'admin.user-detail.plan-entitlements.grant.button': 'Grant entitlement',+ 'admin.user-detail.plan-entitlements.grant.title': 'Grant plan entitlement',+ 'admin.user-detail.plan-entitlements.grant.description':+ 'Grant a plan entitlement to this user, optionally with an expiration date.',+ 'admin.user-detail.plan-entitlements.grant.type-label': 'Entitlement type',+ 'admin.user-detail.plan-entitlements.grant.expiration.toggle': 'Set an expiration date',+ 'admin.user-detail.plan-entitlements.grant.expiration.pick-date': 'Pick a date',+ 'admin.user-detail.plan-entitlements.grant.submit': 'Grant entitlement',+ 'admin.user-detail.plan-entitlements.grant.cancel': 'Cancel',+ 'admin.user-detail.plan-entitlements.grant.success': 'Entitlement granted successfully.',+ 'admin.user-detail.plan-entitlements.revoke.button': 'Revoke',+ 'admin.user-detail.plan-entitlements.revoke.confirm.title': 'Revoke entitlement?',+ 'admin.user-detail.plan-entitlements.revoke.confirm.message':+ 'The user will lose the plan benefits granted by this entitlement.',+ 'admin.user-detail.plan-entitlements.revoke.confirm.confirm-button': 'Revoke entitlement',+ 'admin.user-detail.plan-entitlements.revoke.confirm.cancel-button': 'Cancel',+ 'admin.user-detail.plan-entitlements.revoke.success': 'Entitlement revoked successfully.','admin.user-detail.delete.title': 'Delete user','admin.user-detail.delete.description':'Permanently delete this user account. This will cascade to their organization memberships, sessions, two-factor settings and other authentication data. Organizations they still own must be deleted or transferred first.',diff --git a/apps/papra-client/src/modules/admin/users/components/grant-plan-entitlement-dialog.component.tsx b/apps/papra-client/src/modules/admin/users/components/grant-plan-entitlement-dialog.component.tsxnew file mode 100644index 00000000..0fcf1305--- /dev/null+++ b/apps/papra-client/src/modules/admin/users/components/grant-plan-entitlement-dialog.component.tsx@@ -0,0 +1,189 @@+import type { Component } from 'solid-js';+import Calendar from '@corvu/calendar';+import { useMutation, useQueryClient } from '@tanstack/solid-query';+import { createSignal, Show } from 'solid-js';+import { useI18n } from '@/modules/i18n/i18n.provider';+import { useI18nApiErrors } from '@/modules/shared/http/composables/i18n-api-errors';+import { Button } from '@/modules/ui/components/button';+import { CalendarGrid } from '@/modules/ui/components/calendar';+import { CalendarMonthYearHeader } from '@/modules/ui/components/calendar-month-year-header';+import {+ Dialog,+ DialogContent,+ DialogDescription,+ DialogFooter,+ DialogHeader,+ DialogTitle,+} from '@/modules/ui/components/dialog';+import { Popover, PopoverContent, PopoverTrigger } from '@/modules/ui/components/popover';+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from '@/modules/ui/components/select';+import { createToast } from '@/modules/ui/components/sonner';+import { Switch, SwitchControl, SwitchLabel, SwitchThumb } from '@/modules/ui/components/switch';+import { grantPlanEntitlement } from '../users.services';++export const GrantPlanEntitlementDialog: Component<{+ userId: string;+ availableTypes: string[];+ open: boolean;+ onOpenChange: (open: boolean) => void;+}> = (props) => {+ const { t, formatDate } = useI18n();+ const { getErrorMessage } = useI18nApiErrors({ t });+ const queryClient = useQueryClient();++ const [getType, setType] = createSignal<string | null>(null);+ const [getIsExpirationEnabled, setIsExpirationEnabled] = createSignal(false);+ const [getExpirationDate, setExpirationDate] = createSignal<Date | null>(null);++ function computeExpiresAt(): Date | null {+ const date = getExpirationDate();++ if (!getIsExpirationEnabled() || !date) {+ return null;+ }++ // Expire at the end of the chosen day.+ const day = `${date.getFullYear()}-${`${date.getMonth() + 1}`.padStart(2, '0')}-${`${date.getDate()}`.padStart(2, '0')}`;+ return new Date(`${day}T23:59:59`);+ }++ const canSubmit = () => {+ if (!getType()) {+ return false;+ }++ if (getIsExpirationEnabled() && !getExpirationDate()) {+ return false;+ }++ return true;+ };++ const closeAndReset = () => {+ setType(null);+ setIsExpirationEnabled(false);+ setExpirationDate(null);+ props.onOpenChange(false);+ };++ const grantMutation = useMutation(() => ({+ mutationFn: () =>+ grantPlanEntitlement({+ userId: props.userId,+ type: getType()!,+ expiresAt: computeExpiresAt(),+ }),+ onSuccess: async () => {+ await queryClient.invalidateQueries({ queryKey: ['admin', 'users', props.userId] });+ createToast({+ type: 'success',+ message: t('admin.user-detail.plan-entitlements.grant.success'),+ });+ closeAndReset();+ },+ onError: (error) => {+ createToast({ type: 'error', message: getErrorMessage({ error }) });+ },+ }));++ return (+ <Dialog open={props.open} onOpenChange={props.onOpenChange}>+ <DialogContent class="sm:max-w-[440px]">+ <DialogHeader>+ <DialogTitle>{t('admin.user-detail.plan-entitlements.grant.title')}</DialogTitle>+ <DialogDescription>+ {t('admin.user-detail.plan-entitlements.grant.description')}+ </DialogDescription>+ </DialogHeader>++ <div class="flex flex-col gap-4">+ <div>+ <label class="text-sm font-medium mb-1 block">+ {t('admin.user-detail.plan-entitlements.grant.type-label')}+ </label>+ <Select+ options={props.availableTypes}+ itemComponent={(itemProps) => (+ <SelectItem item={itemProps.item}>+ <span class="font-mono text-sm">{itemProps.item.rawValue}</span>+ </SelectItem>+ )}+ value={getType()}+ onChange={setType}+ >+ <SelectTrigger>+ <SelectValue<string>>+ {(state) => <span class="font-mono text-sm">{state.selectedOption()}</span>}+ </SelectValue>+ </SelectTrigger>+ <SelectContent />+ </Select>+ </div>++ <Switch+ class="flex items-center justify-between gap-4"+ checked={getIsExpirationEnabled()}+ onChange={setIsExpirationEnabled}+ >+ <SwitchLabel class="text-sm font-medium">+ {t('admin.user-detail.plan-entitlements.grant.expiration.toggle')}+ </SwitchLabel>+ <SwitchControl>+ <SwitchThumb />+ </SwitchControl>+ </Switch>++ <Show when={getIsExpirationEnabled()}>+ <Popover>+ <PopoverTrigger as={Button} variant="outline" class="self-start">+ <div class="i-tabler-calendar size-4 mr-2" />+ <Show+ when={getExpirationDate()}+ fallback={t('admin.user-detail.plan-entitlements.grant.expiration.pick-date')}+ >+ {(getDate) => formatDate(getDate(), { dateStyle: 'medium' })}+ </Show>+ </PopoverTrigger>+ <PopoverContent class="w-auto p-3">+ <Calendar+ mode="single"+ value={getExpirationDate()}+ onValueChange={setExpirationDate}+ fixedWeeks+ >+ {() => (+ <div class="flex flex-col gap-2">+ <CalendarMonthYearHeader />+ <CalendarGrid />+ </div>+ )}+ </Calendar>+ </PopoverContent>+ </Popover>+ </Show>+ </div>++ <DialogFooter>+ <div class="flex gap-2 justify-end flex-col-reverse sm:flex-row">+ <Button variant="secondary" onClick={closeAndReset} disabled={grantMutation.isPending}>+ {t('admin.user-detail.plan-entitlements.grant.cancel')}+ </Button>+ <Button+ onClick={() => grantMutation.mutate()}+ disabled={!canSubmit() || grantMutation.isPending}+ isLoading={grantMutation.isPending}+ >+ {t('admin.user-detail.plan-entitlements.grant.submit')}+ </Button>+ </div>+ </DialogFooter>+ </DialogContent>+ </Dialog>+ );+};diff --git a/apps/papra-client/src/modules/admin/users/pages/user-detail.page.tsx b/apps/papra-client/src/modules/admin/users/pages/user-detail.page.tsxindex c0e38e13..16df33bf 100644--- a/apps/papra-client/src/modules/admin/users/pages/user-detail.page.tsx+++ b/apps/papra-client/src/modules/admin/users/pages/user-detail.page.tsx@@ -2,7 +2,7 @@ import type { Component } from 'solid-js';import { safely } from '@corentinth/chisels';import { A, useNavigate, useParams } from '@solidjs/router';import { useQuery, useQueryClient } from '@tanstack/solid-query';-import { For, Show } from 'solid-js';+import { createSignal, For, Show } from 'solid-js';import { RelativeTime } from '@/modules/i18n/components/RelativeTime';import { useI18n } from '@/modules/i18n/i18n.provider';import { useConfirmModal } from '@/modules/shared/confirm';@@ -27,7 +27,9 @@ import {TableRow,} from '@/modules/ui/components/table';import { useCurrentUser } from '@/modules/users/composables/useCurrentUser';-import { deleteUser, getUserDetail } from '../users.services';+import { GrantPlanEntitlementDialog } from '../components/grant-plan-entitlement-dialog.component';+import { deleteUser, getUserDetail, revokePlanEntitlement } from '../users.services';+import { useConfig } from '@/modules/config/config.provider';export const AdminUserDetailPage: Component = () => {const { t } = useI18n();@@ -37,12 +39,48 @@ export const AdminUserDetailPage: Component = () => {const { confirm } = useConfirmModal();const { getErrorMessage } = useI18nApiErrors({ t });const { user: currentUser } = useCurrentUser();+ const { config } = useConfig();++ const [getIsGrantDialogOpen, setIsGrantDialogOpen] = createSignal(false);const query = useQuery(() => ({queryKey: ['admin', 'users', params.userId],queryFn: () => getUserDetail({ userId: params.userId }),}));+ const handleRevokeEntitlement = async (planEntitlement: { id: string; type: string }) => {+ const confirmed = await confirm({+ title: t('admin.user-detail.plan-entitlements.revoke.confirm.title'),+ message: t('admin.user-detail.plan-entitlements.revoke.confirm.message'),+ confirmButton: {+ text: t('admin.user-detail.plan-entitlements.revoke.confirm.confirm-button'),+ variant: 'destructive',+ },+ cancelButton: {+ text: t('admin.user-detail.plan-entitlements.revoke.confirm.cancel-button'),+ },+ });++ if (!confirmed) {+ return;+ }++ const [, error] = await safely(+ revokePlanEntitlement({ userId: params.userId, planEntitlementId: planEntitlement.id }),+ );++ if (error) {+ createToast({ type: 'error', message: getErrorMessage({ error }) });+ return;+ }++ await queryClient.invalidateQueries({ queryKey: ['admin', 'users', params.userId] });+ createToast({+ type: 'success',+ message: t('admin.user-detail.plan-entitlements.revoke.success'),+ });+ };+const handleDelete = async (targetUser: { id: string; email: string }) => {const confirmed = await confirm({title: t('admin.user-detail.delete.confirm.title'),@@ -259,6 +297,131 @@ export const AdminUserDetailPage: Component = () => {</CardContent></Card>+ {config.isSubscriptionsEnabled && (+ <Card>+ <CardHeader class="flex-row items-start justify-between space-y-0 gap-4">+ <div class="space-y-1.5">+ <CardTitle>{t('admin.user-detail.plan-entitlements.title')}</CardTitle>+ <CardDescription>+ {t('admin.user-detail.plan-entitlements.description')}+ </CardDescription>+ </div>+ <Button+ size="sm"+ variant="outline"+ class="flex-shrink-0"+ disabled={data().availablePlanEntitlementTypes.every((type) =>+ data().planEntitlements.some((entitlement) => entitlement.type === type),+ )}+ onClick={() => setIsGrantDialogOpen(true)}+ >+ <div class="i-tabler-plus size-4 mr-2" />+ {t('admin.user-detail.plan-entitlements.grant.button')}+ </Button>+ </CardHeader>+ <CardContent>+ <Show+ when={data().planEntitlements.length > 0}+ fallback={+ <p class="text-sm text-muted-foreground">+ {t('admin.user-detail.plan-entitlements.empty')}+ </p>+ }+ >+ <div class="rounded-md border">+ <Table>+ <TableHeader>+ <TableRow>+ <TableHead>+ {t('admin.user-detail.plan-entitlements.table.type')}+ </TableHead>+ <TableHead>+ {t('admin.user-detail.plan-entitlements.table.source')}+ </TableHead>+ <TableHead>+ {t('admin.user-detail.plan-entitlements.table.granted')}+ </TableHead>+ <TableHead>+ {t('admin.user-detail.plan-entitlements.table.expires')}+ </TableHead>+ <TableHead />+ </TableRow>+ </TableHeader>+ <TableBody>+ <For each={data().planEntitlements}>+ {(entitlement) => (+ <TableRow>+ <TableCell>+ <Badge variant="secondary" class="font-mono">+ {entitlement.type}+ </Badge>+ </TableCell>+ <TableCell>+ <Badge variant="outline" class="font-mono">+ {entitlement.source}+ </Badge>+ </TableCell>+ <TableCell>+ <RelativeTime+ class="text-sm"+ date={new Date(entitlement.grantedAt)}+ />+ </TableCell>+ <TableCell>+ <Show+ when={entitlement.expiresAt}+ fallback={+ <span class="text-sm text-muted-foreground">+ {t('admin.user-detail.plan-entitlements.never-expires')}+ </span>+ }+ >+ {(getExpiresAt) => (+ <span class="flex items-center gap-2">+ <RelativeTime+ class="text-sm"+ date={new Date(getExpiresAt())}+ />+ <Show when={new Date(getExpiresAt()) < new Date()}>+ <Badge variant="destructive" class="text-xs">+ {t('admin.user-detail.plan-entitlements.expired')}+ </Badge>+ </Show>+ </span>+ )}+ </Show>+ </TableCell>+ <TableCell class="text-right">+ <Button+ size="sm"+ variant="ghost"+ class="text-destructive"+ onClick={() => handleRevokeEntitlement(entitlement)}+ >+ {t('admin.user-detail.plan-entitlements.revoke.button')}+ </Button>+ </TableCell>+ </TableRow>+ )}+ </For>+ </TableBody>+ </Table>+ </div>+ </Show>+ </CardContent>+ </Card>+ )}++ <GrantPlanEntitlementDialog+ userId={params.userId}+ availableTypes={data().availablePlanEntitlementTypes.filter(+ (type) =>+ !data().planEntitlements.some((entitlement) => entitlement.type === type),+ )}+ open={getIsGrantDialogOpen()}+ onOpenChange={setIsGrantDialogOpen}+ />+<Card class="border-destructive"><CardHeader><CardTitle>{t('admin.user-detail.delete.title')}</CardTitle>diff --git a/apps/papra-client/src/modules/admin/users/users.services.ts b/apps/papra-client/src/modules/admin/users/users.services.tsindex 00b35c94..ccec8e22 100644--- a/apps/papra-client/src/modules/admin/users/users.services.ts+++ b/apps/papra-client/src/modules/admin/users/users.services.ts@@ -4,6 +4,16 @@ import { apiClient } from '@/modules/shared/http/api-client';export type UserWithOrganizationCount = User & { organizationCount: number };+export type UserPlanEntitlement = {+ id: string;+ type: string;+ source: string;+ grantedAt: string;+ expiresAt: string | null;+ createdAt: string;+ updatedAt: string;+};+export async function listUsers({search,pageIndex = 0,@@ -28,16 +38,48 @@ export async function listUsers({}export async function getUserDetail({ userId }: { userId: string }) {- const { organizations, roles, user } = await apiClient<{- user: User;- organizations: Organization[];- roles: string[];- }>({- method: 'GET',- path: `/api/admin/users/${userId}`,+ const { organizations, roles, user, planEntitlements, availablePlanEntitlementTypes } =+ await apiClient<{+ user: User;+ organizations: Organization[];+ roles: string[];+ planEntitlements: UserPlanEntitlement[];+ availablePlanEntitlementTypes: string[];+ }>({+ method: 'GET',+ path: `/api/admin/users/${userId}`,+ });++ return { organizations, roles, user, planEntitlements, availablePlanEntitlementTypes };+}++export async function grantPlanEntitlement({+ userId,+ type,+ expiresAt,+}: {+ userId: string;+ type: string;+ expiresAt?: Date | null;+}) {+ await apiClient({+ method: 'POST',+ path: `/api/admin/users/${userId}/plan-entitlements`,+ body: { type, expiresAt: expiresAt ? expiresAt.toISOString() : undefined },});+}- return { organizations, roles, user };+export async function revokePlanEntitlement({+ userId,+ planEntitlementId,+}: {+ userId: string;+ planEntitlementId: string;+}) {+ await apiClient({+ method: 'DELETE',+ path: `/api/admin/users/${userId}/plan-entitlements/${planEntitlementId}`,+ });}export async function deleteUser({ userId }: { userId: string }) {diff --git a/apps/papra-server/src/modules/admin/users/e2e/plan-entitlements.e2e.test.ts b/apps/papra-server/src/modules/admin/users/e2e/plan-entitlements.e2e.test.tsnew file mode 100644index 00000000..0066eeba--- /dev/null+++ b/apps/papra-server/src/modules/admin/users/e2e/plan-entitlements.e2e.test.ts@@ -0,0 +1,467 @@+import { eq } from 'drizzle-orm';+import { describe, expect, test } from 'vitest';+import { createInMemoryDatabase } from '../../../app/database/database.test-utils';+import { createServer } from '../../../app/server';+import { createTestServerDependencies } from '../../../app/server.test-utils';+import { overrideConfig } from '../../../config/config.test-utils';+import { planEntitlementsTable } from '../../../plan-entitlements/plan-entitlements.tables';+import {+ createTestPlanEntitlementDriver,+ createTestPlanEntitlementRegistry,+} from '../../../plan-entitlements/plan-entitlements.test-utils';++describe('admin user plan entitlements routes', () => {+ describe('post /api/admin/users/:userId/plan-entitlements', () => {+ test('when the user has the MANAGE_PLAN_ENTITLEMENTS permission, the entitlement is granted with the admin source', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({+ db,+ config: overrideConfig({ env: 'test' }),+ planEntitlementDefinitionRegistry: createTestPlanEntitlementRegistry(),+ }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(200);++ const entitlements = await db+ .select()+ .from(planEntitlementsTable)+ .where(eq(planEntitlementsTable.userId, targetUserId));++ expect(entitlements).to.have.length(1);+ expect(entitlements[0]?.type).to.eql('selfhst-premium');+ expect(entitlements[0]?.source).to.eql('admin');+ expect(entitlements[0]?.expiresAt).to.eql(null);+ expect(entitlements[0]?.grantedAt).to.be.instanceOf(Date);+ expect(entitlements[0]?.lastVerifiedAt).to.be.instanceOf(Date);+ });++ test('when the user is not eligible for the entitlement, a 400 error is returned and no entitlement is created', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({+ db,+ config: overrideConfig({ env: 'test' }),+ planEntitlementDefinitionRegistry: createTestPlanEntitlementRegistry({+ driver: createTestPlanEntitlementDriver({ verifyEligibility: async () => false }),+ }),+ }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(400);+ expect(await response.json()).to.eql({+ error: {+ code: 'plan_entitlements.not_eligible',+ message: 'User is not eligible for this entitlement',+ },+ });++ const entitlements = await db.select().from(planEntitlementsTable);+ expect(entitlements).to.eql([]);+ });++ test('when an expiration date is provided, it is stored on the entitlement', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const expiresAt = '2027-01-01T00:00:00.000Z';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({+ db,+ config: overrideConfig({ env: 'test' }),+ planEntitlementDefinitionRegistry: createTestPlanEntitlementRegistry(),+ }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium', expiresAt }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(200);++ const entitlements = await db+ .select()+ .from(planEntitlementsTable)+ .where(eq(planEntitlementsTable.userId, targetUserId));++ expect(entitlements[0]?.expiresAt).to.eql(new Date(expiresAt));+ });++ test('when the user already has an entitlement of the same type, a 409 error is returned', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ planEntitlements: [+ {+ id: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: targetUserId,+ type: 'selfhst-premium',+ source: 'user-claim',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({+ db,+ config: overrideConfig({ env: 'test' }),+ planEntitlementDefinitionRegistry: createTestPlanEntitlementRegistry(),+ }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(409);+ expect(await response.json()).to.eql({+ error: {+ code: 'plan_entitlements.already_exists',+ message: 'User already has an entitlement of this type',+ },+ });+ });++ test('when the entitlement type is unknown, a 400 error is returned', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'unknown-entitlement' }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(400);+ });++ test('when the target user does not exist, a 404 error is returned', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_admin', email: '[email protected]', name: 'Admin User' }],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ '/api/admin/users/usr_999999999999999999999999/plan-entitlements',+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(404);+ });++ test('when the user does not have the MANAGE_PLAN_ENTITLEMENTS permission, a 401 error is returned and no entitlement is created', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_regular', email: '[email protected]' },+ { id: targetUserId, email: '[email protected]' },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements`,+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ },+ { loggedInUserId: 'usr_regular' },+ );++ expect(response.status).to.eql(401);++ const entitlements = await db.select().from(planEntitlementsTable);+ expect(entitlements).to.eql([]);+ });++ test('when the user is not authenticated, a 401 error is returned', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_target', email: '[email protected]' }],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request('/api/admin/users/usr_target/plan-entitlements', {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ type: 'selfhst-premium' }),+ });++ expect(response.status).to.eql(401);+ });+ });++ describe('delete /api/admin/users/:userId/plan-entitlements/:planEntitlementId', () => {+ test('when the user has the MANAGE_PLAN_ENTITLEMENTS permission, the entitlement is deleted', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const planEntitlementId = 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ planEntitlements: [+ {+ id: planEntitlementId,+ userId: targetUserId,+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements/${planEntitlementId}`,+ { method: 'DELETE' },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(204);++ const remaining = await db.select().from(planEntitlementsTable);+ expect(remaining).to.eql([]);+ });++ test('when the entitlement belongs to a different user, a 404 error is returned and the entitlement is kept', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const otherUserId = 'usr_999999999999999999999999';+ const planEntitlementId = 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ { id: otherUserId, email: '[email protected]', name: 'Other User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ planEntitlements: [+ {+ id: planEntitlementId,+ userId: otherUserId,+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements/${planEntitlementId}`,+ { method: 'DELETE' },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(404);+ expect(await response.json()).to.eql({+ error: {+ code: 'plan_entitlements.not_found',+ message: 'Plan entitlement not found',+ },+ });++ const remaining = await db.select().from(planEntitlementsTable);+ expect(remaining).to.have.length(1);+ });++ test('when the entitlement does not exist, a 404 error is returned', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements/pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa`,+ { method: 'DELETE' },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(404);+ });++ test('when the user does not have the MANAGE_PLAN_ENTITLEMENTS permission, a 401 error is returned and the entitlement is kept', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const planEntitlementId = 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_regular', email: '[email protected]' },+ { id: targetUserId, email: '[email protected]' },+ ],+ planEntitlements: [+ {+ id: planEntitlementId,+ userId: targetUserId,+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}/plan-entitlements/${planEntitlementId}`,+ { method: 'DELETE' },+ { loggedInUserId: 'usr_regular' },+ );++ expect(response.status).to.eql(401);++ const remaining = await db.select().from(planEntitlementsTable);+ expect(remaining).to.have.length(1);+ });+ });++ describe('get /api/admin/users/:userId', () => {+ test('the user detail response includes the plan entitlements and the available entitlement types', async () => {+ const targetUserId = 'usr_123456789012345678901234';+ const planEntitlementId = 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa';+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_admin', email: '[email protected]', name: 'Admin User' },+ { id: targetUserId, email: '[email protected]', name: 'Target User' },+ ],+ userRoles: [{ userId: 'usr_admin', role: 'admin' }],+ planEntitlements: [+ {+ id: planEntitlementId,+ userId: targetUserId,+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const { app } = createServer(+ createTestServerDependencies({ db, config: overrideConfig({ env: 'test' }) }),+ );++ const response = await app.request(+ `/api/admin/users/${targetUserId}`,+ { method: 'GET' },+ { loggedInUserId: 'usr_admin' },+ );++ expect(response.status).to.eql(200);+ const body = (await response.json()) as {+ planEntitlements: { id: string; type: string; source: string }[];+ availablePlanEntitlementTypes: string[];+ };++ expect(body.planEntitlements).to.have.length(1);+ expect(body.planEntitlements[0]?.id).to.eql(planEntitlementId);+ expect(body.planEntitlements[0]?.type).to.eql('selfhst-premium');+ expect(body.planEntitlements[0]?.source).to.eql('admin');+ expect(body.availablePlanEntitlementTypes).to.include('selfhst-premium');+ });+ });+});diff --git a/apps/papra-server/src/modules/admin/users/plan-entitlements/plan-entitlements.routes.ts b/apps/papra-server/src/modules/admin/users/plan-entitlements/plan-entitlements.routes.tsnew file mode 100644index 00000000..f26fc177--- /dev/null+++ b/apps/papra-server/src/modules/admin/users/plan-entitlements/plan-entitlements.routes.ts@@ -0,0 +1,93 @@+import type { RouteDefinitionContext } from '../../../app/server.types';+import * as v from 'valibot';+import { createRoleMiddleware, requireAuthentication } from '../../../app/auth/auth.middleware';+import { PLAN_ENTITLEMENT_SOURCES } from '../../../plan-entitlements/plan-entitlements.constants';+import { createPlanEntitlementsRepository } from '../../../plan-entitlements/plan-entitlements.repository';+import {+ planEntitlementIdSchema,+ planEntitlementTypeSchema,+} from '../../../plan-entitlements/plan-entitlements.schemas';+import { grantUserPlanEntitlement } from '../../../plan-entitlements/plan-entitlements.usecases';+import { PERMISSIONS } from '../../../roles/roles.constants';+import { validateJsonBody, validateParams } from '../../../shared/validation/validation';+import { createUsersRepository } from '../../../users/users.repository';+import { userIdSchema } from '../../../users/users.schemas';++export function registerUserPlanEntitlementsRoutes(context: RouteDefinitionContext) {+ registerGrantPlanEntitlementRoute(context);+ registerRevokePlanEntitlementRoute(context);+}++function registerGrantPlanEntitlementRoute({+ app,+ db,+ planEntitlementDefinitionRegistry,+}: RouteDefinitionContext) {+ const { requirePermissions } = createRoleMiddleware({ db });++ app.post(+ '/api/admin/users/:userId/plan-entitlements',+ requireAuthentication(),+ requirePermissions({+ requiredPermissions: [PERMISSIONS.MANAGE_PLAN_ENTITLEMENTS],+ }),+ validateParams(+ v.strictObject({+ userId: userIdSchema,+ }),+ ),+ validateJsonBody(+ v.strictObject({+ type: planEntitlementTypeSchema,+ expiresAt: v.optional(v.nullable(v.pipe(v.string(), v.isoTimestamp(), v.toDate()))),+ }),+ ),+ async (context) => {+ const { userId } = context.req.valid('param');+ const { type, expiresAt } = context.req.valid('json');++ const usersRepository = createUsersRepository({ db });+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });++ await usersRepository.getUserByIdOrThrow({ userId });++ const { planEntitlement } = await grantUserPlanEntitlement({+ userId,+ type,+ expiresAt,+ source: PLAN_ENTITLEMENT_SOURCES.ADMIN,+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ });++ return context.json({ planEntitlement });+ },+ );+}++function registerRevokePlanEntitlementRoute({ app, db }: RouteDefinitionContext) {+ const { requirePermissions } = createRoleMiddleware({ db });++ app.delete(+ '/api/admin/users/:userId/plan-entitlements/:planEntitlementId',+ requireAuthentication(),+ requirePermissions({+ requiredPermissions: [PERMISSIONS.MANAGE_PLAN_ENTITLEMENTS],+ }),+ validateParams(+ v.strictObject({+ userId: userIdSchema,+ planEntitlementId: planEntitlementIdSchema,+ }),+ ),+ async (context) => {+ const { userId, planEntitlementId } = context.req.valid('param');++ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });++ await planEntitlementsRepository.deleteUserPlanEntitlement({ planEntitlementId, userId });++ return context.body(null, 204);+ },+ );+}diff --git a/apps/papra-server/src/modules/admin/users/users.routes.ts b/apps/papra-server/src/modules/admin/users/users.routes.tsindex 04645f88..b9feee87 100644--- a/apps/papra-server/src/modules/admin/users/users.routes.ts+++ b/apps/papra-server/src/modules/admin/users/users.routes.ts@@ -4,6 +4,8 @@ import { createRoleMiddleware, requireAuthentication } from '../../app/auth/authimport { getUser } from '../../app/auth/auth.models';import { getUserMaxOrganizationCount } from '../../organizations/organizations.models';import { createOrganizationsRepository } from '../../organizations/organizations.repository';+import { planEntitlementsDefinitionFactories } from '../../plan-entitlements/plan-entitlements.registry';+import { createPlanEntitlementsRepository } from '../../plan-entitlements/plan-entitlements.repository';import { PERMISSIONS } from '../../roles/roles.constants';import { createRolesRepository } from '../../roles/roles.repository';import { createQueryPaginationSchemaKeys } from '../../shared/schemas/pagination.schemas';@@ -12,11 +14,13 @@ import { createCannotDeleteSelfError } from '../../users/users.errors';import { createUsersRepository } from '../../users/users.repository';import { userIdSchema } from '../../users/users.schemas';import { deleteUser } from '../../users/users.usecases';+import { registerUserPlanEntitlementsRoutes } from './plan-entitlements/plan-entitlements.routes';export function registerUserManagementRoutes(context: RouteDefinitionContext) {registerListUsersRoute(context);registerGetUserDetailRoute(context);registerDeleteUserRoute(context);+ registerUserPlanEntitlementsRoutes(context);}function registerListUsersRoute({ app, db }: RouteDefinitionContext) {@@ -73,12 +77,16 @@ function registerGetUserDetailRoute({ app, db, config }: RouteDefinitionContext)const usersRepository = createUsersRepository({ db });const organizationsRepository = createOrganizationsRepository({ db });const rolesRepository = createRolesRepository({ db });+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });const { userId } = context.req.valid('param');- const { user } = await usersRepository.getUserByIdOrThrow({ userId });- const { organizations } = await organizationsRepository.getUserOrganizations({ userId });- const { roles } = await rolesRepository.getUserRoles({ userId });+ const [{ user }, { organizations }, { roles }, { planEntitlements }] = await Promise.all([+ usersRepository.getUserByIdOrThrow({ userId }),+ organizationsRepository.getUserOrganizations({ userId }),+ rolesRepository.getUserRoles({ userId }),+ planEntitlementsRepository.getUserPlanEntitlements({ userId }),+ ]);return context.json({user: {@@ -87,6 +95,8 @@ function registerGetUserDetailRoute({ app, db, config }: RouteDefinitionContext)},organizations,roles,+ planEntitlements,+ availablePlanEntitlementTypes: Object.keys(planEntitlementsDefinitionFactories),});},);diff --git a/apps/papra-server/src/modules/app/server.routes.test.ts b/apps/papra-server/src/modules/app/server.routes.test.tsindex cc8293fa..19c83421 100644--- a/apps/papra-server/src/modules/app/server.routes.test.ts+++ b/apps/papra-server/src/modules/app/server.routes.test.ts@@ -22,7 +22,8 @@ function setValidParams(path: string) {.replaceAll(':optionId', 'cpso_222222222222222222222222').replaceAll(':shareLinkId', 'dsl_333333333333333333333333').replaceAll(':shareLinkToken', 't'.repeat(SHARE_LINK_TOKEN_LENGTH))- .replaceAll(':documentViewId', 'dv_444444444444444444444444');+ .replaceAll(':documentViewId', 'dv_444444444444444444444444')+ .replaceAll(':planEntitlementId', 'pla_ent_555555555555555555555555');// throw if there are any remaining paramsif (newPath.match(/:\w+/g)) {diff --git a/apps/papra-server/src/modules/app/server.test-utils.ts b/apps/papra-server/src/modules/app/server.test-utils.tsindex 27d46772..409e6c56 100644--- a/apps/papra-server/src/modules/app/server.test-utils.ts+++ b/apps/papra-server/src/modules/app/server.test-utils.ts@@ -46,7 +46,9 @@ export function createTestServerDependencies(webhookRepository: createWebhookRepository({ db }),});const kvStore = overrides.kvStore ?? createKvStore({ driver: createInMemoryKvStoreDriver() });- const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });+ const planEntitlementDefinitionRegistry =+ overrides.planEntitlementDefinitionRegistry ??+ createPlanEntitlementDefinitionRegistry({ config });registerEventHandlers({eventServices,diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.errors.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.errors.tsnew file mode 100644index 00000000..652bf8d1--- /dev/null+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.errors.ts@@ -0,0 +1,25 @@+import { createErrorFactory } from '../shared/errors/errors';++export const createPlanEntitlementAlreadyExistsError = createErrorFactory({+ message: 'User already has an entitlement of this type',+ code: 'plan_entitlements.already_exists',+ statusCode: 409,+});++export const createPlanEntitlementNotFoundError = createErrorFactory({+ message: 'Plan entitlement not found',+ code: 'plan_entitlements.not_found',+ statusCode: 404,+});++export const createPlanEntitlementUnknownTypeError = createErrorFactory({+ message: 'Unknown plan entitlement type',+ code: 'plan_entitlements.unknown_type',+ statusCode: 400,+});++export const createPlanEntitlementNotEligibleError = createErrorFactory({+ message: 'User is not eligible for this entitlement',+ code: 'plan_entitlements.not_eligible',+ statusCode: 400,+});diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.test.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.test.tsnew file mode 100644index 00000000..ea174031--- /dev/null+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.test.ts@@ -0,0 +1,160 @@+import { describe, expect, test } from 'vitest';+import { createInMemoryDatabase } from '../app/database/database.test-utils';+import { createTestClock } from '../shared/clock/clock.test-utils';+import { createPlanEntitlementsRepository } from './plan-entitlements.repository';++describe('plan-entitlements repository', () => {+ describe('createPlanEntitlement', () => {+ test('the grantedAt date is taken from the clock', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });+ const { clock } = createTestClock({ now: Temporal.Instant.from('2026-06-01T12:00:00Z') });++ const repository = createPlanEntitlementsRepository({ db, clock });++ const { planEntitlement } = await repository.createPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ });++ expect(planEntitlement?.grantedAt).to.eql(new Date('2026-06-01T12:00:00Z'));+ expect(planEntitlement?.expiresAt).to.eql(null);+ expect(planEntitlement?.source).to.eql('admin');+ });++ test('when the user already has an entitlement of the same type, an already-exists error is raised', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ planEntitlements: [+ {+ id: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'user-claim',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const repository = createPlanEntitlementsRepository({ db });++ await expect(+ repository.createPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ }),+ ).rejects.toThrowError('User already has an entitlement of this type');+ });+ });++ describe('getUserPlanEntitlements', () => {+ test('only the entitlements of the given user are returned, including expired ones', async () => {+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_1', email: '[email protected]' },+ { id: 'usr_2', email: '[email protected]' },+ ],+ planEntitlements: [+ {+ id: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ expiresAt: new Date('2026-02-01'),+ },+ {+ id: 'pla_ent_bbbbbbbbbbbbbbbbbbbbbbbb',+ userId: 'usr_2',+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const repository = createPlanEntitlementsRepository({ db });++ const { planEntitlements } = await repository.getUserPlanEntitlements({ userId: 'usr_1' });++ expect(planEntitlements).to.have.length(1);+ expect(planEntitlements[0]?.id).to.eql('pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa');+ expect(planEntitlements[0]?.expiresAt).to.eql(new Date('2026-02-01'));+ });+ });++ describe('deleteUserPlanEntitlement', () => {+ test('the entitlement is deleted when it belongs to the given user', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ planEntitlements: [+ {+ id: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const repository = createPlanEntitlementsRepository({ db });++ await repository.deleteUserPlanEntitlement({+ planEntitlementId: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ });++ const { planEntitlements } = await repository.getUserPlanEntitlements({ userId: 'usr_1' });+ expect(planEntitlements).to.eql([]);+ });++ test('when the entitlement belongs to another user, a not-found error is raised and the entitlement is kept', async () => {+ const { db } = await createInMemoryDatabase({+ users: [+ { id: 'usr_1', email: '[email protected]' },+ { id: 'usr_2', email: '[email protected]' },+ ],+ planEntitlements: [+ {+ id: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ grantedAt: new Date('2026-01-01'),+ },+ ],+ });++ const repository = createPlanEntitlementsRepository({ db });++ await expect(+ repository.deleteUserPlanEntitlement({+ planEntitlementId: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_2',+ }),+ ).rejects.toThrowError('Plan entitlement not found');++ const { planEntitlements } = await repository.getUserPlanEntitlements({ userId: 'usr_1' });+ expect(planEntitlements).to.have.length(1);+ });++ test('when the entitlement does not exist, a not-found error is raised', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });++ const repository = createPlanEntitlementsRepository({ db });++ await expect(+ repository.deleteUserPlanEntitlement({+ planEntitlementId: 'pla_ent_aaaaaaaaaaaaaaaaaaaaaaaa',+ userId: 'usr_1',+ }),+ ).rejects.toThrowError('Plan entitlement not found');+ });+ });+});diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.tsindex 6c889c0d..733d9a3f 100644--- a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts@@ -8,6 +8,13 @@ import { organizationMembersTable } from '../organizations/organizations.table';import { ORGANIZATION_ROLES } from '../organizations/organizations.constants';import type { Logger } from '@crowlog/logger';import { createLogger } from '../shared/logger/logger';+import { isUniqueConstraintError } from '../shared/db/constraints.models';+import type { PlanEntitlementSource } from './plan-entitlements.constants';+import type { PlanEntitlementType } from './plan-entitlements.registry';+import {+ createPlanEntitlementAlreadyExistsError,+ createPlanEntitlementNotFoundError,+} from './plan-entitlements.errors';export type PlanEntitlementsRepository = ReturnType<typeof createPlanEntitlementsRepository>;@@ -20,7 +27,88 @@ export function createPlanEntitlementsRepository({clock?: Clock;logger?: Logger;}) {- return injectArguments({ getActiveEntitlementForOrganization }, { db, clock, logger });+ return injectArguments(+ {+ getActiveEntitlementForOrganization,+ getUserPlanEntitlements,+ createPlanEntitlement,+ deleteUserPlanEntitlement,+ },+ { db, clock, logger },+ );+}++async function getUserPlanEntitlements({ db, userId }: { db: Database; userId: string }) {+ const planEntitlements = await db+ .select()+ .from(planEntitlementsTable)+ .where(eq(planEntitlementsTable.userId, userId));++ return { planEntitlements };+}++async function createPlanEntitlement({+ db,+ userId,+ type,+ source,+ expiresAt,+ lastVerifiedAt,+ clock = systemClock,+}: {+ db: Database;+ userId: string;+ type: PlanEntitlementType;+ source: PlanEntitlementSource;+ expiresAt?: Date | null;+ lastVerifiedAt?: Date | null;+ clock?: Clock;+}) {+ try {+ const [planEntitlement] = await db+ .insert(planEntitlementsTable)+ .values({+ userId,+ type,+ source,+ expiresAt: expiresAt ?? null,+ lastVerifiedAt: lastVerifiedAt ?? null,+ grantedAt: new Date(clock.now().epochMilliseconds),+ })+ .returning();++ return { planEntitlement };+ } catch (error) {+ if (isUniqueConstraintError({ error })) {+ throw createPlanEntitlementAlreadyExistsError();+ }++ throw error;+ }+}++async function deleteUserPlanEntitlement({+ db,+ planEntitlementId,+ userId,+}: {+ db: Database;+ planEntitlementId: string;+ userId: string;+}) {+ const deleted = await db+ .delete(planEntitlementsTable)+ .where(+ and(+ eq(planEntitlementsTable.id, planEntitlementId),+ eq(planEntitlementsTable.userId, userId),+ ),+ )+ .returning({ id: planEntitlementsTable.id });++ if (deleted.length === 0) {+ throw createPlanEntitlementNotFoundError();+ }}async function getActiveEntitlementForOrganization({diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.schemas.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.schemas.tsnew file mode 100644index 00000000..ea09e423--- /dev/null+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.schemas.ts@@ -0,0 +1,11 @@+import * as v from 'valibot';+import { createRegexSchema } from '../shared/schemas/string.schemas';+import { planEntitlementIdRegex } from './plan-entitlements.constants';+import type { PlanEntitlementType } from './plan-entitlements.registry';+import { planEntitlementsDefinitionFactories } from './plan-entitlements.registry';++export const planEntitlementIdSchema = createRegexSchema(planEntitlementIdRegex);++export const planEntitlementTypeSchema = v.picklist(+ Object.keys(planEntitlementsDefinitionFactories) as PlanEntitlementType[],+);diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.test-utils.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.test-utils.tsnew file mode 100644index 00000000..f7007843--- /dev/null+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.test-utils.ts@@ -0,0 +1,28 @@+import { PLAN_IDS } from '../plans/plans.constants';+import type { PlanEntitlementDefinitionRegistry } from './plan-entitlements.registry';+import type { PlanEntitlementDriver } from './plan-entitlements.types';++export function createTestPlanEntitlementDriver(+ overrides: Partial<PlanEntitlementDriver> = {},+): PlanEntitlementDriver {+ return {+ planId: PLAN_IDS.FREE_EXTENDED,+ verifyEligibility: async () => true,+ getIsEnabledForNewClaims: async () => true,+ ...overrides,+ };+}++export function createTestPlanEntitlementRegistry({+ driver = createTestPlanEntitlementDriver(),+}: { driver?: PlanEntitlementDriver } = {}): PlanEntitlementDefinitionRegistry {+ return {+ getPlanEntitlementDriver: () => ({ planEntitlementDriver: driver }),+ };+}++export function createEmptyTestPlanEntitlementRegistry(): PlanEntitlementDefinitionRegistry {+ return {+ getPlanEntitlementDriver: () => ({ planEntitlementDriver: undefined }),+ };+}diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.test.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.test.tsnew file mode 100644index 00000000..a27476db--- /dev/null+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.test.ts@@ -0,0 +1,111 @@+import { describe, expect, test } from 'vitest';+import { createInMemoryDatabase } from '../app/database/database.test-utils';+import { createTestClock } from '../shared/clock/clock.test-utils';+import { createPlanEntitlementsRepository } from './plan-entitlements.repository';+import {+ createEmptyTestPlanEntitlementRegistry,+ createTestPlanEntitlementDriver,+ createTestPlanEntitlementRegistry,+} from './plan-entitlements.test-utils';+import { grantUserPlanEntitlement } from './plan-entitlements.usecases';++describe('plan-entitlements usecases', () => {+ describe('grantUserPlanEntitlement', () => {+ test('when the user is eligible, the entitlement is created and marked as verified', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });+ const { clock } = createTestClock({ now: Temporal.Instant.from('2026-06-01T12:00:00Z') });++ const planEntitlementsRepository = createPlanEntitlementsRepository({ db, clock });+ const planEntitlementDefinitionRegistry = createTestPlanEntitlementRegistry({+ driver: createTestPlanEntitlementDriver({ verifyEligibility: async () => true }),+ });++ const { planEntitlement } = await grantUserPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ clock,+ });++ expect(planEntitlement?.lastVerifiedAt).to.eql(new Date('2026-06-01T12:00:00Z'));+ expect(planEntitlement?.grantedAt).to.eql(new Date('2026-06-01T12:00:00Z'));+ expect(planEntitlement?.source).to.eql('admin');+ });++ test('when the user is not eligible, a not-eligible error is raised and no entitlement is created', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });++ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });+ const planEntitlementDefinitionRegistry = createTestPlanEntitlementRegistry({+ driver: createTestPlanEntitlementDriver({ verifyEligibility: async () => false }),+ });++ await expect(+ grantUserPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ }),+ ).rejects.toThrowError('User is not eligible for this entitlement');++ const { planEntitlements } = await planEntitlementsRepository.getUserPlanEntitlements({+ userId: 'usr_1',+ });+ expect(planEntitlements).to.eql([]);+ });++ test('the eligibility is verified for the target user', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });++ const verifiedUserIds: string[] = [];+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });+ const planEntitlementDefinitionRegistry = createTestPlanEntitlementRegistry({+ driver: createTestPlanEntitlementDriver({+ verifyEligibility: async ({ userId }) => {+ verifiedUserIds.push(userId);+ return true;+ },+ }),+ });++ await grantUserPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ });++ expect(verifiedUserIds).to.eql(['usr_1']);+ });++ test('when no driver exists for the entitlement type, an unknown-type error is raised', async () => {+ const { db } = await createInMemoryDatabase({+ users: [{ id: 'usr_1', email: '[email protected]' }],+ });++ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });+ const planEntitlementDefinitionRegistry = createEmptyTestPlanEntitlementRegistry();++ await expect(+ grantUserPlanEntitlement({+ userId: 'usr_1',+ type: 'selfhst-premium',+ source: 'admin',+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ }),+ ).rejects.toThrowError('Unknown plan entitlement type');+ });+ });+});diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.tsindex ad382d7c..f5cdfcc7 100644--- a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts@@ -1,10 +1,62 @@import type { Logger } from '@crowlog/logger';import type { PlanId } from '../plans/plans.constants';+import { systemClock } from '../shared/clock/clock';+import type { Clock } from '../shared/clock/clock.types';import { isNil } from '../shared/utils';-import type { PlanEntitlementDefinitionRegistry } from './plan-entitlements.registry';+import type { PlanEntitlementSource } from './plan-entitlements.constants';+import {+ createPlanEntitlementNotEligibleError,+ createPlanEntitlementUnknownTypeError,+} from './plan-entitlements.errors';+import type {+ PlanEntitlementDefinitionRegistry,+ PlanEntitlementType,+} from './plan-entitlements.registry';import type { PlanEntitlementsRepository } from './plan-entitlements.repository';import { createLogger } from '../shared/logger/logger';+export async function grantUserPlanEntitlement({+ userId,+ type,+ source,+ expiresAt,+ planEntitlementsRepository,+ planEntitlementDefinitionRegistry,+ clock = systemClock,+}: {+ userId: string;+ type: PlanEntitlementType;+ source: PlanEntitlementSource;+ expiresAt?: Date | null;+ planEntitlementsRepository: PlanEntitlementsRepository;+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;+ clock?: Clock;+}) {+ const { planEntitlementDriver } = planEntitlementDefinitionRegistry.getPlanEntitlementDriver({+ type,+ });++ if (isNil(planEntitlementDriver)) {+ throw createPlanEntitlementUnknownTypeError();+ }++ const isEligible = await planEntitlementDriver.verifyEligibility({ userId });++ if (!isEligible) {+ throw createPlanEntitlementNotEligibleError();+ }++ const { planEntitlement } = await planEntitlementsRepository.createPlanEntitlement({+ userId,+ type,+ source,+ expiresAt,+ lastVerifiedAt: new Date(clock.now().epochMilliseconds),+ });++ return { planEntitlement };+}+export async function resolveOrganizationPlanEntitlements({organizationId,planEntitlementsRepository,diff --git a/apps/papra-server/src/modules/roles/roles.constants.ts b/apps/papra-server/src/modules/roles/roles.constants.tsindex 85de33cb..4ed04e41 100644--- a/apps/papra-server/src/modules/roles/roles.constants.ts+++ b/apps/papra-server/src/modules/roles/roles.constants.ts@@ -7,6 +7,7 @@ export const PERMISSIONS = {VIEW_USERS: 'users:view',DELETE_USERS: 'users:delete',VIEW_ANALYTICS: 'analytics:view',+ MANAGE_PLAN_ENTITLEMENTS: 'plan-entitlements:manage',} as const;export const PERMISSIONS_BY_ROLE = {@@ -15,6 +16,7 @@ export const PERMISSIONS_BY_ROLE = {PERMISSIONS.DELETE_USERS,PERMISSIONS.BO_ACCESS,PERMISSIONS.VIEW_ANALYTICS,+ PERMISSIONS.MANAGE_PLAN_ENTITLEMENTS,],} as const;