Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(server): prevent certain emails domain from registering (#638)

Corentin Thomassetae3abe9ec71b
diff --git a/.changeset/big-squids-slide.md b/.changeset/big-squids-slide.md
new file mode 100644
index 00000000..39fc2922
--- /dev/null
+++ b/.changeset/big-squids-slide.md
@@ -0,0 +1,5 @@
+---
+"@papra/docker": patch
+---
+
+Added the possibility to filter out some email domain names for new registration
diff --git a/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.test.ts b/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.test.ts
new file mode 100644
index 00000000..90f66932
--- /dev/null
+++ b/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.test.ts
@@ -0,0 +1,292 @@
+import { FetchError } from 'ofetch';
+import { describe, expect, test } from 'vitest';
+
+import { useI18nApiErrors } from './i18n-api-errors';
+
+function t(key: string) {
+ const translations: Record<string, string> = {
+ 'api-errors.default': 'An error occurred',
+ 'api-errors.USER_NOT_FOUND': 'User not found',
+ 'api-errors.INVALID_CREDENTIALS': 'Invalid credentials',
+ 'api-errors.auth.invalid_origin': 'Invalid origin',
+ };
+
+ return translations[key] ?? '';
+};
+
+describe('useI18nApiErrors', () => {
+ describe('getErrorMessage', () => {
+ test('extracts error message from code in data.error.code path', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ data: {
+ error: {
+ code: 'USER_NOT_FOUND',
+ },
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('User not found');
+ });
+
+ test('extracts error message from code in details.code path', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ details: {
+ code: 'INVALID_CREDENTIALS',
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Invalid credentials');
+ });
+
+ test('extracts error message from code in code path', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'USER_NOT_FOUND',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('User not found');
+ });
+
+ test('handles Better Auth INVALID_ORIGIN error code', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'INVALID_ORIGIN',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Invalid origin');
+ });
+
+ test('handles Better Auth INVALID_CALLBACKURL error code', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'INVALID_CALLBACKURL',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Invalid origin');
+ });
+
+ test('handles Better Auth INVALID_REDIRECTURL error code', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'INVALID_REDIRECTURL',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Invalid origin');
+ });
+
+ test('uses default message when code translation is not found', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'UNKNOWN_ERROR_CODE',
+ message: 'Something went wrong',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Something went wrong');
+ });
+
+ test('extracts message from data.error.message path when code is not available', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ data: {
+ error: {
+ message: 'Custom error message',
+ },
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Custom error message');
+ });
+
+ test('extracts message from details.message path when code is not available', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ details: {
+ message: 'Custom details message',
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Custom details message');
+ });
+
+ test('extracts message from message path when code is not available', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ message: 'Generic error message',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Generic error message');
+ });
+
+ test('prioritizes details.code over code when both are present', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'USER_NOT_FOUND',
+ details: {
+ code: 'INVALID_CREDENTIALS',
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Invalid credentials');
+ });
+
+ test('prioritizes details.message over message when both are present and code is not available', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ message: 'Generic message',
+ details: {
+ message: 'Detailed message',
+ },
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Detailed message');
+ });
+
+ test('uses default message for FetchError without code', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = new FetchError('Network error');
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('An error occurred');
+ });
+
+ test('uses custom default message when provided', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = new FetchError('Network error');
+
+ const message = getErrorMessage({ error, defaultMessage: 'Custom default' });
+
+ expect(message).toBe('Custom default');
+ });
+
+ test('uses default message for unknown error structure', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {};
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('An error occurred');
+ });
+
+ test('handles null error', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const message = getErrorMessage({ error: null });
+
+ expect(message).toBe('An error occurred');
+ });
+
+ test('handles undefined error', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const message = getErrorMessage({ error: undefined });
+
+ expect(message).toBe('An error occurred');
+ });
+
+ test('handles non-string code value', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 12345,
+ message: 'Fallback message',
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('Fallback message');
+ });
+
+ test('handles non-string message value', () => {
+ const { getErrorMessage } = useI18nApiErrors({ t });
+
+ const error = {
+ message: 12345,
+ };
+
+ const message = getErrorMessage({ error });
+
+ expect(message).toBe('An error occurred');
+ });
+ });
+
+ describe('createI18nApiError', () => {
+ test('creates an Error with the translated message', () => {
+ const { createI18nApiError } = useI18nApiErrors({ t });
+
+ const error = {
+ code: 'USER_NOT_FOUND',
+ };
+
+ const resultError = createI18nApiError({ error });
+
+ expect(resultError).toBeInstanceOf(Error);
+ expect(resultError.message).toBe('User not found');
+ });
+
+ test('creates an Error with the default message for unknown error', () => {
+ const { createI18nApiError } = useI18nApiErrors({ t });
+
+ const error = {};
+
+ const resultError = createI18nApiError({ error });
+
+ expect(resultError).toBeInstanceOf(Error);
+ expect(resultError.message).toBe('An error occurred');
+ });
+
+ test('creates an Error with custom message from error', () => {
+ const { createI18nApiError } = useI18nApiErrors({ t });
+
+ const error = {
+ message: 'Custom error',
+ };
+
+ const resultError = createI18nApiError({ error });
+
+ expect(resultError).toBeInstanceOf(Error);
+ expect(resultError.message).toBe('Custom error');
+ });
+ });
+});
diff --git a/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.ts b/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.ts
index 4c5fcb49..1dfdf35d 100644
--- a/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.ts
+++ b/apps/papra-client/src/modules/shared/http/composables/i18n-api-errors.ts
@@ -1,5 +1,4 @@
import type { TranslationKeys } from '@/modules/i18n/locales.types';
-import { castError } from '@corentinth/chisels';
import { FetchError } from 'ofetch';
import { useI18n } from '@/modules/i18n/i18n.provider';
import { get } from '@/modules/shared/utils/get';
@@ -15,39 +14,45 @@ function codeToKey(code: string): TranslationKeys {
}
export function useI18nApiErrors({ t = useI18n().t }: { t?: ReturnType<typeof useI18n>['t'] } = {}) {
- const getDefaultErrorMessage = () => t('api-errors.default');
-
- const getErrorMessage = (args: { error: unknown } | { code: string }) => {
- if ('code' in args) {
- const { code } = args;
- return t(codeToKey(code)) ?? getDefaultErrorMessage();
- }
-
- if ('error' in args) {
- const error = castError(args.error);
- const code = get(error, ['data', 'error', 'code'], ['code']);
- const translation = code && typeof code === 'string' ? t(codeToKey(code)) : undefined;
-
+ const getErrorMessage = ({ error, defaultMessage = t('api-errors.default') }: { error: unknown; defaultMessage?: string }) => {
+ const code = get(
+ error,
+ ['data', 'error', 'code'], // From fetch errors
+ ['details', 'code'], // From custom errors throw in better auth hooks, must be before ['code'] as they have both
+ ['code'], // From generic errors
+ );
+
+ if (code && typeof code === 'string') {
+ const translation = t(codeToKey(code));
+
+ // Fallback to potential error message if translation not found
if (translation) {
return translation;
}
+ }
- // Fetch error message is not helpful
- if (error instanceof FetchError) {
- return getDefaultErrorMessage();
- }
+ // Fetch error messages without codes are not helpful
+ if (error instanceof FetchError) {
+ return defaultMessage;
+ }
- if (typeof error === 'object' && error && 'message' in error && typeof error.message === 'string') {
- return error.message;
- }
+ const message = get(
+ error,
+ ['data', 'error', 'message'], // From fetch errors
+ ['details', 'message'], // From custom errors throw in better auth hooks, must be before ['message'] as they have both
+ ['message'], // From generic errors
+ );
+
+ if (message && typeof message === 'string') {
+ return message;
}
- return getDefaultErrorMessage();
+ return defaultMessage;
};
return {
getErrorMessage,
- createI18nApiError: (args: { error: unknown } | { code: string }) => {
+ createI18nApiError: (args: { error: unknown }) => {
return new Error(getErrorMessage(args));
},
};
diff --git a/apps/papra-client/vitest.config.ts b/apps/papra-client/vitest.config.ts
index fca640ba..a58bd963 100644
--- a/apps/papra-client/vitest.config.ts
+++ b/apps/papra-client/vitest.config.ts
@@ -1,3 +1,4 @@
+import path from 'node:path';
import { defineConfig } from 'vitest/config';
export default defineConfig({
@@ -6,4 +7,9 @@ export default defineConfig({
TZ: 'UTC',
},
},
+ resolve: {
+ alias: {
+ '@': path.resolve(__dirname, './src'),
+ },
+ },
});
diff --git a/apps/papra-server/src/modules/app/auth/auth.config.ts b/apps/papra-server/src/modules/app/auth/auth.config.ts
index f3b87074..9816ef3b 100644
--- a/apps/papra-server/src/modules/app/auth/auth.config.ts
+++ b/apps/papra-server/src/modules/app/auth/auth.config.ts
@@ -57,7 +57,7 @@ export const authConfig = {
},
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".
+- If behind a standard proxy, you might want to set this to "x-forwarded-for".
- If behind Cloudflare, you might want to set this to "cf-connecting-ip".`,
schema: z.union([
z.string(),
@@ -66,6 +66,19 @@ export const authConfig = {
default: ['x-forwarded-for'],
env: 'AUTH_IP_ADDRESS_HEADERS',
},
+ forbiddenEmailDomains: {
+ doc: 'A comma separated list of email domains that are forbidden for registration (e.g. "foo.com,bar.com"), if set, it will override the default forbidden domains.',
+ schema: z.union([
+ z.string(),
+ z.array(z.string()),
+ ]).transform((value) => {
+ const asArray = typeof value === 'string' ? value.split(',') : value;
+ const cleaned = asArray.map(v => v.trim().toLowerCase()).filter(v => v.length > 0);
+ return new Set(cleaned);
+ }),
+ default: ['papra.app', 'papra.email', 'owlrelay.email', 'callback.email', 'clb.email'],
+ env: 'AUTH_FORBIDDEN_EMAIL_DOMAINS',
+ },
providers: {
email: {
isEnabled: {
diff --git a/apps/papra-server/src/modules/app/auth/auth.errors.ts b/apps/papra-server/src/modules/app/auth/auth.errors.ts
index 098bb17e..b70b2dcc 100644
--- a/apps/papra-server/src/modules/app/auth/auth.errors.ts
+++ b/apps/papra-server/src/modules/app/auth/auth.errors.ts
@@ -11,3 +11,9 @@ export const createForbiddenError = createErrorFactory({
code: 'auth.forbidden',
statusCode: 403,
});
+
+export const createForbiddenEmailDomainError = createErrorFactory({
+ message: 'Email domain is not allowed',
+ code: 'auth.forbidden_email_domain',
+ statusCode: 403,
+});
diff --git a/apps/papra-server/src/modules/app/auth/auth.models.test.ts b/apps/papra-server/src/modules/app/auth/auth.models.test.ts
index 3bc8b226..8cf95cc2 100644
--- a/apps/papra-server/src/modules/app/auth/auth.models.test.ts
+++ b/apps/papra-server/src/modules/app/auth/auth.models.test.ts
@@ -2,7 +2,7 @@ import type { ApiKey, ApiKeyPermissions } from '../../api-keys/api-keys.types';
import type { Config } from '../../config/config.types';
import type { Session } from './auth.types';
import { describe, expect, test } from 'vitest';
-import { getTrustedOrigins, isAuthenticationValid } from './auth.models';
+import { getTrustedOrigins, isAuthenticationValid, isEmailDomainAllowed } from './auth.models';
describe('auth models', () => {
describe('getTrustedOrigins', () => {
@@ -193,4 +193,88 @@ describe('auth models', () => {
})).to.eql(true);
});
});
+
+ describe('isEmailDomainAllowed', () => {
+ test('when no forbidden domains are configured, all email domains are allowed', () => {
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains: undefined,
+ })).to.eql(true);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains: new Set(),
+ })).to.eql(true);
+ });
+
+ test('when an email domain is in the forbidden list, the email is rejected', () => {
+ const forbiddenEmailDomains = new Set(['tempmail.com', 'disposable.email']);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+ });
+
+ test('when an email domain is not in the forbidden list, the email is allowed', () => {
+ const forbiddenEmailDomains = new Set(['tempmail.com', 'disposable.email']);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(true);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(true);
+ });
+
+ test('email domain matching is case-insensitive', () => {
+ const forbiddenEmailDomains = new Set(['tempmail.com']);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected]',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+ });
+
+ test('when an email has no @ symbol, it is rejected', () => {
+ const forbiddenEmailDomains = new Set(['notanemail']);
+
+ expect(isEmailDomainAllowed({
+ email: 'notanemail',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+
+ expect(isEmailDomainAllowed({
+ email: 'notanemail@',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+ });
+
+ test('email domains with whitespace are properly trimmed before checking', () => {
+ const forbiddenEmailDomains = new Set(['tempmail.com']);
+
+ expect(isEmailDomainAllowed({
+ email: '[email protected] ',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+
+ expect(isEmailDomainAllowed({
+ email: 'user@ tempmail.com ',
+ forbiddenEmailDomains,
+ })).to.eql(false);
+ });
+ });
});
diff --git a/apps/papra-server/src/modules/app/auth/auth.models.ts b/apps/papra-server/src/modules/app/auth/auth.models.ts
index be42b15e..ba5d8f62 100644
--- a/apps/papra-server/src/modules/app/auth/auth.models.ts
+++ b/apps/papra-server/src/modules/app/auth/auth.models.ts
@@ -5,7 +5,7 @@ import type { Session } from './auth.types';
import { uniq } from 'lodash-es';
import { getClientBaseUrl } from '../../config/config.models';
import { createError } from '../../shared/errors/errors';
-import { isNil } from '../../shared/utils';
+import { isNil, isNilOrEmptyString } from '../../shared/utils';
export function getUser({ context }: { context: Context }) {
const userId = context.get('userId');
@@ -84,3 +84,26 @@ export function isAuthenticationValid({
return false;
}
+
+export function isEmailDomainAllowed({
+ email,
+ forbiddenEmailDomains,
+}: {
+ email: string;
+ /**
+ * A set of toLowerCased forbidden email domains (e.g. "papra.app", "callback.email")
+ */
+ forbiddenEmailDomains?: Set<string>;
+}): boolean {
+ if (isNil(forbiddenEmailDomains) || forbiddenEmailDomains.size === 0) {
+ return true;
+ }
+
+ const emailDomain = email.split('@').at(1)?.trim().toLowerCase();
+
+ if (isNilOrEmptyString(emailDomain)) {
+ return false;
+ }
+
+ return !forbiddenEmailDomains.has(emailDomain);
+}
diff --git a/apps/papra-server/src/modules/app/auth/auth.services.ts b/apps/papra-server/src/modules/app/auth/auth.services.ts
index 159b7fe7..5fdbcc62 100644
--- a/apps/papra-server/src/modules/app/auth/auth.services.ts
+++ b/apps/papra-server/src/modules/app/auth/auth.services.ts
@@ -8,7 +8,8 @@ import { genericOAuth } from 'better-auth/plugins';
import { getServerBaseUrl } from '../../config/config.models';
import { createLogger } from '../../shared/logger/logger';
import { usersTable } from '../../users/users.table';
-import { getTrustedOrigins } from './auth.models';
+import { createForbiddenEmailDomainError } from './auth.errors';
+import { getTrustedOrigins, isEmailDomainAllowed } from './auth.models';
import { accountsTable, sessionsTable, verificationsTable } from './auth.tables';
export type Auth = ReturnType<typeof getAuth>['auth'];
@@ -79,6 +80,11 @@ export function getAuth({
databaseHooks: {
user: {
create: {
+ before: async ({ email }) => {
+ if (!isEmailDomainAllowed({ email, forbiddenEmailDomains: config.auth.forbiddenEmailDomains })) {
+ throw createForbiddenEmailDomainError();
+ }
+ },
after: async ({ id: userId, email }) => {
logger.info({ userId }, 'User signed up');
trackingServices.captureUserEvent({ userId, event: 'User signed up', properties: { $set: { email } } });
diff --git a/apps/papra-server/src/modules/shared/utils.test.ts b/apps/papra-server/src/modules/shared/utils.test.ts
index be1848fd..b88e7e8d 100644
--- a/apps/papra-server/src/modules/shared/utils.test.ts
+++ b/apps/papra-server/src/modules/shared/utils.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, test } from 'vitest';
-import { isDefined, isNil, isNonEmptyString, isString, nullifyPositiveInfinity, omitUndefined } from './utils';
+import { isDefined, isNil, isNilOrEmptyString, isNonEmptyString, isString, nullifyPositiveInfinity, omitUndefined } from './utils';
describe('utils', () => {
describe('omitUndefined', () => {
@@ -91,4 +91,20 @@ describe('utils', () => {
expect(nullifyPositiveInfinity(Number.NEGATIVE_INFINITY)).to.eql(Number.NEGATIVE_INFINITY);
});
});
+
+ describe('isNilOrEmptyString', () => {
+ test('returns true for undefined, null, or empty string', () => {
+ expect(isNilOrEmptyString(undefined)).toBe(true);
+ expect(isNilOrEmptyString(null)).toBe(true);
+ expect(isNilOrEmptyString('')).toBe(true);
+ });
+
+ test('returns false for non-empty strings and other types', () => {
+ expect(isNilOrEmptyString('foo')).toBe(false);
+ expect(isNilOrEmptyString(0)).toBe(false);
+ expect(isNilOrEmptyString(false)).toBe(false);
+ expect(isNilOrEmptyString({})).toBe(false);
+ expect(isNilOrEmptyString([])).toBe(false);
+ });
+ });
});
diff --git a/apps/papra-server/src/modules/shared/utils.ts b/apps/papra-server/src/modules/shared/utils.ts
index 9889b43b..79c32271 100644
--- a/apps/papra-server/src/modules/shared/utils.ts
+++ b/apps/papra-server/src/modules/shared/utils.ts
@@ -12,6 +12,10 @@ export function isNil(value: unknown): value is undefined | null {
return value === undefined || value === null;
}
+export function isNilOrEmptyString(value: unknown): value is null | undefined | '' {
+ return isNil(value) || (isString(value) && value.length === 0);
+}
+
export function isDefined<T>(value: T): value is Exclude<T, undefined | null> {
return !isNil(value);
}