The minimalistic document archiving platform.
feat(admin): added first user admin role assignment and related documentation (#723)
Corentin Thomasset68d848e622f8
diff --git a/.changeset/fine-aliens-jump.md b/.changeset/fine-aliens-jump.mdnew file mode 100644index 00000000..059048cc--- /dev/null+++ b/.changeset/fine-aliens-jump.md@@ -0,0 +1,5 @@+---+"@papra/docker": patch+---++Auto assign admin role to the first user registeringdiff --git a/apps/docs/src/content/docs/03-guides/07-roles-and-permissions.mdx b/apps/docs/src/content/docs/03-guides/07-roles-and-permissions.mdxnew file mode 100644index 00000000..19260213--- /dev/null+++ b/apps/docs/src/content/docs/03-guides/07-roles-and-permissions.mdx@@ -0,0 +1,140 @@+---+title: Roles and Administration+slug: guides/roles-administration+description: Understanding platform roles and admin access in Papra.+---+import { Aside } from '@astrojs/starlight/components';++This guide explains the roles and permissions system in Papra, focusing on platform-wide roles and how to manage admin access.++<Aside type="note">+ The administration features are available starting from Papra version `26.0.0`.+</Aside>++## Overview++Papra has two separate role systems:++1. **Platform Roles** - System-wide roles like `admin` for managing the entire Papra instance+2. **Organization Roles** - Workspace-level roles like `owner` and `member` for managing organizations++This guide focuses on platform roles and admin access.++## Platform Roles++### Admin Role++The `admin` role provides system-wide administrative privileges. Admins can:++- **User Management**: View all users, their organizations, and activity+- **Analytics**: Access platform-wide usage statistics and metrics+- **Backoffice Access**: Full access to the admin panel at `/admin`++<Aside type="tip">+ At the moment, the admin panel is focused on read-only operations for monitoring and analytics. Additional management capabilities (user moderation, deletion, system configuration, etc.) will be added in future releases.+</Aside>++## Accessing the Admin Panel++Users with the `admin` role can access the admin panel by navigating to:++```+https://your-papra-instance.com/admin+```++Or click on the `Admin` button in the navigation bar (visible only to admins).++## First User as Admin++### Overview++For self-hosted instances, Papra can automatically assign the `admin` role to the first user who registers. This simplifies initial setup by ensuring you have admin access from the start.++### How It Works++1. User registers (first person to create an account)+2. Account is created successfully+3. System checks if this is the first user (user count === 1)+4. The `admin` role is assigned to this user+5. User immediately has admin panel access+6. Subsequent users are normal users without admin privileges++### Configuration++The auto-assignment of the admin role to the first user is controlled by the `AUTH_FIRST_USER_AS_ADMIN` environment variable.+It is enabled by default for self-hosted instances, but can be disabled by setting it to `false`:++```bash+AUTH_FIRST_USER_AS_ADMIN=false+```++### Security Considerations++**Race Conditions:**+If multiple users register simultaneously, at most one will receive the admin role. The system checks `userCount === 1` and uses idempotent role assignment to prevent duplicate admin grants.++**Recommended Practice:**+1. Register your admin account first+2. Disable the feature after setup: `AUTH_FIRST_USER_AS_ADMIN=false`+3. Restart the service if you changed the config++## Manual Admin Assignment++For existing installations with already registered users, you can manually assign the `admin` role using the CLI script `script:make-user-admin`.++Run the following command, replacing `<user-email-or-id>` with the email or ID of the user you want to promote to admin:++```bash+pnpm script:make-user-admin <user-email-or-id>+```++In docker, assuming your container is named `papra`, run:++```bash+docker exec -it papra pnpm script:make-user-admin <user-email-or-id>+```++## Admin Panel Features++### User Management++Navigate to `/admin/users` to:+- View all registered users+- Search users by email, name, or ID+- See user organization memberships+- View user roles and permissions+- Monitor user activity++### Analytics++Navigate to `/admin/analytics` to:+- View registration trends+- Monitor document processing stats+- Track system usage metrics++### Organizations++Navigate to `/admin/organizations` to:+- View all organizations+- Monitor organization activity+- See organization member counts++## Troubleshooting++### I registered but don't have admin access++You can manually assign admin using the script. See the [Manual Admin Assignment](#manual-admin-assignment) section.++### How do I check if a user has admin?++In the admin panel, navigate to the user management section and search for the user. Their roles will be listed in their profile.++### Can I have multiple admins?++Yes, you can assign the `admin` role to multiple users.++## Related Documentation++- [Configuration Guide](/self-hosting/configuration)+- [Docker Setup](/self-hosting/using-docker)+- [CLI Reference](/resources/cli)diff --git a/apps/docs/src/content/navigation.ts b/apps/docs/src/content/navigation.tsindex 04407a5b..1701efed 100644--- a/apps/docs/src/content/navigation.ts+++ b/apps/docs/src/content/navigation.ts@@ -45,6 +45,11 @@ export const sidebar = [label: 'Tagging Rules',slug: 'guides/tagging-rules',},+ // Will be uncommented after release+ // {+ // label: 'Roles and Administration',+ // slug: 'guides/roles-administration',+ // },],},{diff --git a/apps/papra-server/src/modules/app/auth/auth.config.ts b/apps/papra-server/src/modules/app/auth/auth.config.tsindex cad37c59..e76c6f85 100644--- a/apps/papra-server/src/modules/app/auth/auth.config.ts+++ b/apps/papra-server/src/modules/app/auth/auth.config.ts@@ -56,6 +56,12 @@ export const authConfig = {default: false,env: 'AUTH_SHOW_LEGAL_LINKS',},+ firstUserAsAdmin: {+ doc: 'Automatically assign the admin role to the first user who registers. This is useful for initial setup of self-hosted instances where you need an admin account to manage the platform.',+ schema: booleanishSchema,+ default: true,+ env: 'AUTH_FIRST_USER_AS_ADMIN',+ },ipAddressHeaders: {doc: `The header, or comma separated list of headers, to use to get the real IP address of the user, use for rate limiting. Make sur to use a non-spoofable header, one set by your proxy.- If behind a standard proxy, you might want to set this to "x-forwarded-for".diff --git a/apps/papra-server/src/modules/app/events/events.handlers.ts b/apps/papra-server/src/modules/app/events/events.handlers.tsindex eebcac45..4760924a 100644--- a/apps/papra-server/src/modules/app/events/events.handlers.ts+++ b/apps/papra-server/src/modules/app/events/events.handlers.ts@@ -1,3 +1,4 @@+import type { Config } from '../../config/config.types';import type { DocumentSearchServices } from '../../documents/document-search/document-search.types';import type { TrackingServices } from '../../tracking/tracking.services';import type { Database } from '../database/database.types';@@ -11,9 +12,11 @@ import { registerTrackDocumentCreatedHandler } from '../../documents/events/tracimport { registerTriggerWebhooksOnDocumentCreatedHandler } from '../../documents/events/webhook.document-created';import { registerTriggerWebhooksOnDocumentTrashedHandler } from '../../documents/events/webhook.document-trashed';import { registerTriggerWebhooksOnDocumentUpdatedHandler } from '../../documents/events/webhook.document-updated';+import { registerFirstUserAdminEventHandler } from '../../roles/event-handlers/first-user-admin.user-created';import { registerTrackingUserCreatedEventHandler } from '../../users/event-handlers/tracking.user-created';-export function registerEventHandlers(deps: { trackingServices: TrackingServices; eventServices: EventServices; db: Database; documentSearchServices: DocumentSearchServices }) {+export function registerEventHandlers(deps: { trackingServices: TrackingServices; eventServices: EventServices; db: Database; documentSearchServices: DocumentSearchServices; config: Config }) {+ registerFirstUserAdminEventHandler(deps);registerTrackingUserCreatedEventHandler(deps);registerTriggerWebhooksOnDocumentCreatedHandler(deps);registerInsertActivityLogOnDocumentCreatedHandler(deps);diff --git a/apps/papra-server/src/modules/app/server.test-utils.ts b/apps/papra-server/src/modules/app/server.test-utils.tsindex ee7ed2d0..c8b6e4ef 100644--- a/apps/papra-server/src/modules/app/server.test-utils.ts+++ b/apps/papra-server/src/modules/app/server.test-utils.ts@@ -29,7 +29,7 @@ export function createTestServerDependencies(overrides: Partial<GlobalDependenciconst subscriptionsServices = overrides.subscriptionsServices ?? createSubscriptionsServices({ config });const documentSearchServices = overrides.documentSearchServices ?? createDocumentSearchServices({ db, config });- registerEventHandlers({ eventServices, trackingServices, db, documentSearchServices });+ registerEventHandlers({ eventServices, trackingServices, db, documentSearchServices, config });return {config,diff --git a/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.test.ts b/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.test.tsnew file mode 100644index 00000000..1b73d1e6--- /dev/null+++ b/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.test.ts@@ -0,0 +1,129 @@+import { createNoopLogger } from '@crowlog/logger';+import { describe, expect, test } from 'vitest';+import { createInMemoryDatabase } from '../../app/database/database.test-utils';+import { createEventServices } from '../../app/events/events.services';+import { overrideConfig } from '../../config/config.test-utils';+import { nextTick } from '../../shared/async/defer.test-utils';+import { usersTable } from '../../users/users.table';+import { userRolesTable } from '../roles.table';+import { registerFirstUserAdminEventHandler } from './first-user-admin.user-created';++describe('first user admin assignment', () => {+ describe('when the feature is disabled', () => {+ test('the first user does not receive admin role', async () => {+ const user = { id: 'usr_1', email: '[email protected]', createdAt: new Date('2026-01-01') };++ const { db } = await createInMemoryDatabase({ users: [user] });+ const eventServices = createEventServices();++ const config = overrideConfig({ auth: { firstUserAsAdmin: false } });++ registerFirstUserAdminEventHandler({ eventServices, config, db, logger: createNoopLogger() });++ eventServices.emitEvent({ eventName: 'user.created', payload: { userId: user.id, ...user } });++ await nextTick();++ const roles = await db.select().from(userRolesTable);+ expect(roles).to.deep.equal([]);+ });+ });++ describe('when the feature is enabled', () => {+ test('the first user receives the admin role automatically', async () => {+ const user = { id: 'usr_1', email: '[email protected]', createdAt: new Date('2026-01-01') };++ const { db } = await createInMemoryDatabase({ users: [user] });+ const eventServices = createEventServices();++ const config = overrideConfig({ auth: { firstUserAsAdmin: true } });++ registerFirstUserAdminEventHandler({ eventServices, config, db, logger: createNoopLogger() });++ eventServices.emitEvent({ eventName: 'user.created', payload: { userId: user.id, ...user } });++ await nextTick();++ const roles = await db.select().from(userRolesTable);+ expect(+ roles.map(({ userId, role }) => ({ userId, role })),+ ).to.deep.equal([+ { userId: 'usr_1', role: 'admin' },+ ]);+ });++ test('if the first user already has an admin role, it does not fail', async () => {+ const user = { id: 'usr_1', email: '[email protected]', createdAt: new Date('2026-01-01') };+ const { db } = await createInMemoryDatabase({+ users: [user],+ userRoles: [{ userId: user.id, role: 'admin' }],+ });+ const eventServices = createEventServices();++ const config = overrideConfig({ auth: { firstUserAsAdmin: true } });++ registerFirstUserAdminEventHandler({ eventServices, config, db, logger: createNoopLogger() });++ eventServices.emitEvent({ eventName: 'user.created', payload: { userId: user.id, ...user } });++ await nextTick();++ const roles = await db.select().from(userRolesTable);+ expect(+ roles.map(({ userId, role }) => ({ userId, role })),+ ).to.deep.equal([+ { userId: 'usr_1', role: 'admin' },+ ]);+ });++ test('the second user does not receive the admin role', async () => {+ const { db } = await createInMemoryDatabase();+ const eventServices = createEventServices();++ const config = overrideConfig({ auth: { firstUserAsAdmin: true } });++ registerFirstUserAdminEventHandler({ eventServices, config, db, logger: createNoopLogger() });++ const firstUser = { id: 'usr_1', email: '[email protected]', createdAt: new Date('2026-01-01') };+ await db.insert(usersTable).values(firstUser);++ eventServices.emitEvent({ eventName: 'user.created', payload: { userId: firstUser.id, ...firstUser } });+ await nextTick();++ const secondUser = { id: 'usr_2', email: '[email protected]', createdAt: new Date('2026-01-02') };+ await db.insert(usersTable).values(secondUser);++ eventServices.emitEvent({ eventName: 'user.created', payload: { userId: secondUser.id, ...secondUser } });+ await nextTick();++ const roles = await db.select().from(userRolesTable);+ expect(+ roles.map(({ userId, role }) => ({ userId, role })),+ ).to.deep.equal([+ { userId: 'usr_1', role: 'admin' },+ ]);+ });++ test('when multiple users are already created, no one receives the admin role', async () => {+ const users = [+ { id: 'usr_1', email: '[email protected]', createdAt: new Date('2026-01-01') },+ { id: 'usr_2', email: '[email protected]', createdAt: new Date('2026-01-01') },+ ].map(user => ({ ...user, userId: user.id }));++ const { db } = await createInMemoryDatabase({ users });+ const eventServices = createEventServices();++ const config = overrideConfig({ auth: { firstUserAsAdmin: true } });++ registerFirstUserAdminEventHandler({ eventServices, config, db, logger: createNoopLogger() });++ eventServices.emitEvent({ eventName: 'user.created', payload: users[0]! });+ eventServices.emitEvent({ eventName: 'user.created', payload: users[1]! });++ await nextTick();+ const roles = await db.select().from(userRolesTable);++ expect(roles.length).to.equal(0);+ });+ });+});diff --git a/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.ts b/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.tsnew file mode 100644index 00000000..6e399572--- /dev/null+++ b/apps/papra-server/src/modules/roles/event-handlers/first-user-admin.user-created.ts@@ -0,0 +1,48 @@+import type { Database } from '../../app/database/database.types';+import type { EventServices } from '../../app/events/events.services';+import type { Config } from '../../config/config.types';+import type { Logger } from '../../shared/logger/logger';+import { createLogger } from '../../shared/logger/logger';+import { createUsersRepository } from '../../users/users.repository';+import { ROLES } from '../roles.constants';+import { createRolesRepository } from '../roles.repository';++export function registerFirstUserAdminEventHandler({+ eventServices,+ config,+ logger = createLogger({ namespace: 'events:first-user-admin' }),+ db,+}: {+ eventServices: EventServices;+ config: Config;+ db: Database;+ logger?: Logger;+}) {+ const usersRepository = createUsersRepository({ db });+ const rolesRepository = createRolesRepository({ db });++ if (!config.auth.firstUserAsAdmin) {+ return;+ }++ eventServices.onEvent({+ eventName: 'user.created',+ handlerName: 'roles.assign-admin-to-first-user',+ handler: async ({ userId }) => {+ if (!config.auth.firstUserAsAdmin) {+ return;+ }++ const { userCount } = await usersRepository.getUserCount();++ if (userCount !== 1) {+ logger.debug({ userId, userCount }, 'User is not the first user, skipping admin assignment');+ return;+ }++ await rolesRepository.assignRoleToUser({ userId, role: ROLES.ADMIN });++ logger.info({ userId }, 'Admin role assigned to first user');+ },+ });+}diff --git a/apps/papra-server/src/modules/roles/roles.constants.ts b/apps/papra-server/src/modules/roles/roles.constants.tsindex a8b25888..12476d53 100644--- a/apps/papra-server/src/modules/roles/roles.constants.ts+++ b/apps/papra-server/src/modules/roles/roles.constants.ts@@ -1,3 +1,7 @@+export const ROLES = {+ ADMIN: 'admin',+} as const;+export const PERMISSIONS = {BO_ACCESS: 'bo:access',VIEW_USERS: 'users:view',@@ -5,11 +9,11 @@ export const PERMISSIONS = {} as const;export const PERMISSIONS_BY_ROLE = {- admin: [+ [ROLES.ADMIN]: [PERMISSIONS.VIEW_USERS,PERMISSIONS.BO_ACCESS,PERMISSIONS.VIEW_ANALYTICS,],} as const;-export const ROLES = Object.keys(PERMISSIONS_BY_ROLE) as (keyof typeof PERMISSIONS_BY_ROLE)[];+export const ROLES_LIST = Object.values(ROLES);diff --git a/apps/papra-server/src/modules/roles/roles.repository.ts b/apps/papra-server/src/modules/roles/roles.repository.tsindex 4da32a72..917758b2 100644--- a/apps/papra-server/src/modules/roles/roles.repository.ts+++ b/apps/papra-server/src/modules/roles/roles.repository.ts@@ -38,8 +38,7 @@ async function assignRoleToUser({ userId, role, db }: { userId: string; role: RouserId,role,})- .onConflictDoNothing()- .returning();+ .onConflictDoNothing();}async function removeRoleFromUser({ userId, role, db }: { userId: string; role: Role; db: Database }) {diff --git a/apps/papra-server/src/modules/roles/roles.types.ts b/apps/papra-server/src/modules/roles/roles.types.tsindex 444d3bbf..5af8f627 100644--- a/apps/papra-server/src/modules/roles/roles.types.ts+++ b/apps/papra-server/src/modules/roles/roles.types.ts@@ -1,4 +1,4 @@-import type { PERMISSIONS, ROLES } from './roles.constants';+import type { PERMISSIONS, ROLES_LIST } from './roles.constants';-export type Role = typeof ROLES[number];+export type Role = typeof ROLES_LIST[number];export type Permission = typeof PERMISSIONS[keyof typeof PERMISSIONS];diff --git a/apps/papra-server/src/start.ts b/apps/papra-server/src/start.tsindex 08e1e381..e0dbb7d9 100644--- a/apps/papra-server/src/start.ts+++ b/apps/papra-server/src/start.ts@@ -63,7 +63,7 @@ async function buildServices({ config }: { config: Config }): Promise<GlobalDepe// --- Services initializationawait taskServices.initialize();- registerEventHandlers({ eventServices, trackingServices, db, documentSearchServices });+ registerEventHandlers({ eventServices, trackingServices, db, documentSearchServices, config });return {config,