feat(perm): central permission registry + key validation in linter

- backend/src/permissions/registry.js: single source of truth (PERMISSIONS map)
  with all 24 keys (16 teacher + 8 student, student keys also cover free_student).
  Exports isKnown(), listKeys(), byRole(), buildDefaultsMap().
- auth.js: PERM_DEFAULTS now sourced from registry.buildDefaultsMap();
  new perm() helper validates key at registration time (crashes early on typos).
  requirePermission() unchanged — backward compat preserved.
- permissionsController.js: ALL_PERMISSIONS now built from registry.byRole();
  inline 24-entry array removed. API response shape unchanged.
- check-route-auth.js: validates every requirePermission/perm call key against
  registry; lists unknown keys as errors before exit.
  perm() added to GUARDS list so it counts as route protection.

Discrepancy noted: auth.js had free_student with same 8 keys as student;
permissionsController never seeded free_student rows. Registry documents
this via roles:[] array; buildDefaultsMap() correctly covers free_student.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/scripts/check-route-auth.js

@@ -32,8 +32,9 @@
  */
 
 'use strict';
-const fs   = require('fs');
-const path = require('path');
+const fs       = require('fs');
+const path     = require('path');
+const registry = require('../src/permissions/registry');
 
 const ROUTES_DIR = path.join(__dirname, '../src/routes');
 
@@ -42,6 +43,7 @@ const GUARDS = [
   'requireOwnership',
   'requireRole',
   'requirePermission',
+  'perm',           // ergonomic alias from auth.js that validates key at registration time
   'parentAuth',
   'authMiddleware',
   'requireAuth',
@@ -128,6 +130,33 @@ function main() {
 
   console.log(`Route auth check: ${total} :id-routes total, ${unprotected} unprotected (baseline: ${BASELINE})`);
 
+  /* ── Permission key validation ───────────────────────────────────────── */
+  // Scan all route files for requirePermission('X') and perm('X') calls.
+  // Verify each key exists in the central registry.
+  const permKeyRe = /(?:requirePermission|perm)\(\s*['"`]([^'"`]+)['"`]/g;
+  const unknownPermKeys = [];
+  for (const file of files) {
+    const src = fs.readFileSync(file, 'utf8');
+    let m;
+    permKeyRe.lastIndex = 0;
+    while ((m = permKeyRe.exec(src)) !== null) {
+      const key = m[1];
+      if (!registry.isKnown(key)) {
+        unknownPermKeys.push({ file: path.basename(file), key });
+      }
+    }
+  }
+  if (unknownPermKeys.length > 0) {
+    console.error('\nFAIL: requirePermission/perm calls with keys not in registry:');
+    for (const { file, key } of unknownPermKeys) {
+      console.error(`  ${file}: "${key}"`);
+    }
+    console.error('Add missing keys to backend/src/permissions/registry.js');
+    process.exit(1);
+  } else {
+    console.log('Permission key check: all requirePermission/perm keys are registered.');
+  }
+
   if (unprotected > BASELINE) {
     console.error(`\nFAIL: ${unprotected - BASELINE} new unprotected route(s) added above baseline.`);
     console.error('Add requireOwnership/requireRole/requirePermission, or mark intentional:');