Skip to content

armgit / papra

Public Imported from GitHub
0

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.ts
index 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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/auth
import { 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.ts
index 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 params
if (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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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;