fix: forbid backendOnly on primary key AdminForth/1934/list-rows-lose-their-primary-k

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: srelon

adminforth/documentation/docs/tutorial/03-Customization/12-security.md

@@ -296,6 +296,8 @@ So to completely hide the email field from all users apart superadmins, you shou
 
 So if you will configure the email column in user resource like this, only superadmin will be able to see emails, and only in the list view.
 
+> ☝️ `backendOnly` cannot be set on a primary key column (neither `true` nor a function): frontend needs primary key values to build record links, so AdminForth refuses such config on startup.
+
 ## Blocking login attempts before credentials check
 
 `auth.beforeLoginAttempt` hooks are called on every request to the login endpoint, before AdminForth looks the user up in the database.

adminforth/modules/configValidator.ts

@@ -527,6 +527,12 @@ export default class ConfigValidator implements IConfigValidator {
           errors.push(`Resource "${res.resourceId}" has duplicate column name "${col.name}"`);
         }
 
+        // frontend builds record links from primary key values, so they must always reach it.
+        // a backendOnly function is rejected too: it can hide the key only for some users
+        if (col.primaryKey && col.backendOnly) {
+          errors.push(`Resource "${res.resourceId}" column "${col.name}" is a primary key and cannot be backendOnly`);
+        }
+
         col.label = col.label || guessLabelFromName(col.name);
         //define default sortable
         if (!Object.keys(col).includes('sortable')) { col.sortable = !col.virtual; }

adminforth/types/Common.ts

@@ -1037,6 +1037,7 @@ export interface AdminForthResourceColumnInputCommon {
 
   /**
    * if true field will !not be passed to UI under no circumstances, but will be presented in hooks
+   * Not allowed on primary key columns.
    */
   backendOnly?: boolean,
 

tests/jest_tests/primary_key_backend_only.test.ts

@@ -0,0 +1,54 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const applicationDir = path.resolve(currentDir, '../application');
+
+// resolves to the BUILT package (adminforth/dist) the test application runs on;
+// rebuild it (`npx tsc` in adminforth/) after editing configValidator or the assertions below test stale code
+const require = createRequire(import.meta.url);
+const adminforthEntry = require.resolve('adminforth', { paths: [applicationDir] });
+const { default: AdminForth } = await import(pathToFileURL(adminforthEntry).href);
+
+function appWithPkColumn(pkColumn: Record<string, unknown>) {
+  // AdminForth allows one instance per process; each test needs a fresh one
+  delete (globalThis as any).adminforth;
+  return new AdminForth({
+    baseUrl: '',
+    auth: {
+      usersResourceId: 'adminuser',
+      usernameField: 'email',
+      passwordHashField: 'password_hash',
+    },
+    dataSources: [{ id: 'sqlite', url: `sqlite://${path.join(applicationDir, '.db.sqlite')}` }],
+    resources: [{
+      resourceId: 'adminuser',
+      table: 'adminuser',
+      dataSource: 'sqlite',
+      columns: [
+        { name: 'id', primaryKey: true, ...pkColumn },
+        { name: 'email', required: true },
+        { name: 'password_hash', backendOnly: true },
+      ],
+    }],
+    menu: [{ label: 'Users', resourceId: 'adminuser' }],
+  });
+}
+
+const pkBackendOnlyError = /column "id" is a primary key and cannot be backendOnly/;
+
+describe('primary key column cannot be backendOnly', () => {
+  it('rejects backendOnly: true on the primary key', () => {
+    expect(() => appWithPkColumn({ backendOnly: true })).toThrow(pkBackendOnlyError);
+  });
+
+  it('rejects backendOnly function on the primary key', () => {
+    expect(() => appWithPkColumn({ backendOnly: () => false })).toThrow(pkBackendOnlyError);
+  });
+
+  it('accepts backendOnly: false on the primary key and backendOnly on other columns', () => {
+    expect(() => appWithPkColumn({ backendOnly: false })).not.toThrow();
+    expect(() => appWithPkColumn({})).not.toThrow();
+  });
+});