audit: 33-agent comprehensive audit + critical fixes

Full team audit run, all reports verbatim in docs/AUDIT-2026-05-12.md
(5900+ lines, 30+ critical findings). Already-fixed this commit:
- permission-overrides PUT: self-target block + RolePermissions allow-list + cross-tenant guard
- /api/auth/resolve-identifier: rate-limit + synthetic miss-email kill enumeration
- admin email-change: rotates account.accountId + revokes sessions
- middleware: token-gated email confirm/cancel routes whitelisted
- NAV_CATALOG: 10 dead-link sweeps to existing /admin/<x> targets

Feature work landing same commit: optional username sign-in
(migration 0054), per-user permission overrides (0055) with three-state
matrix tabbed inside UserForm, user disable button, role + outcome +
stage label normalisation across the platform, admin email-change
with auto-notification template.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/db/migrations/0054_user_profiles_username.sql

@@ -0,0 +1,31 @@
+-- 0054_user_profiles_username.sql
+-- ----------------------------------------------------------------------------
+-- Optional username as a sign-in alternative to email. Stored alongside the
+-- canonical first/last name on user_profiles so the rest of the auth/profile
+-- code keeps a single place to look. The Better-Auth `user` table stays the
+-- source of truth for email + password; the username is a thin alias the
+-- login form looks up to resolve to the matching email before delegating
+-- to better-auth's email/password flow.
+--
+-- Constraints (enforced application-side AND in SQL):
+--   - 2..30 characters
+--   - lowercase letters, digits, dot, underscore, hyphen
+--   - case-insensitive uniqueness per install (no per-port scoping —
+--     reps move between ports and a global username keeps URLs stable)
+--
+-- The column is nullable; existing users keep email-only sign-in until they
+-- pick one.
+
+ALTER TABLE user_profiles
+  ADD COLUMN IF NOT EXISTS username TEXT;
+
+-- Shape check at the DB level catches anything that slipped past the API
+-- (raw SQL inserts in tests, scripts, etc.).
+ALTER TABLE user_profiles
+  ADD CONSTRAINT chk_user_profiles_username_shape
+    CHECK (username IS NULL OR username ~ '^[a-z0-9._-]{2,30}$');
+
+-- Case-insensitive uniqueness. Partial so multiple NULLs are allowed.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_profiles_username_unique
+  ON user_profiles (LOWER(username))
+  WHERE username IS NOT NULL;

src/lib/db/migrations/0055_user_permission_overrides.sql

@@ -0,0 +1,26 @@
+-- 0055_user_permission_overrides.sql
+-- ----------------------------------------------------------------------------
+-- Per-user permission overrides layered on top of the role's baseline.
+-- Effective permission = role[resource][action]
+--                        |> apply port_role_overrides for that port
+--                        |> apply user_permission_overrides for (user, port)
+--
+-- A user override entry is OPTIONAL — most users will never have one.
+-- When present, the JSONB blob is a Partial<RolePermissions> map where any
+-- explicitly-set leaf wins over the inherited value (true forces grant,
+-- false forces deny, missing → inherit).
+
+CREATE TABLE IF NOT EXISTS user_permission_overrides (
+  id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  user_id TEXT NOT NULL,
+  port_id TEXT NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
+  permission_overrides JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_perm_overrides_user_port
+  ON user_permission_overrides (user_id, port_id);
+
+CREATE INDEX IF NOT EXISTS idx_user_perm_overrides_user
+  ON user_permission_overrides (user_id);

src/lib/db/schema/users.ts

@@ -244,6 +244,14 @@ export const userProfiles = pgTable(
     firstName: text('first_name'),
     lastName: text('last_name'),
     displayName: text('display_name').notNull(),
+    /**
+     * Optional sign-in alias. Lowercase a-z0-9 plus dot/underscore/hyphen,
+     * 3–30 chars (shape pinned by `chk_user_profiles_username_shape`).
+     * Case-insensitive uniqueness is enforced by a partial unique index on
+     * LOWER(username); NULL allows the column to coexist with users who
+     * still sign in by email. See migration 0054.
+     */
+    username: text('username'),
     avatarUrl: text('avatar_url'),
     /** FK into the polymorphic `files` table — the avatar is stored
      *  via getStorageBackend() so an S3↔filesystem swap carries it
@@ -278,6 +286,42 @@ export const roles = pgTable('roles', {
   updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 });
 
+/**
+ * Per-user permission overrides layered on top of the role's baseline for
+ * a specific port. Each row carries a `Partial<RolePermissions>` map; any
+ * explicitly-set leaf wins over the role + port-role-override chain. Most
+ * users will never have a row here — it exists for the rare "give Alice
+ * the same role as her team but let her run permanent deletes" case.
+ *
+ * Effective permission resolution lives in `getEffectivePermissions` in
+ * src/lib/services/permissions.service.ts.
+ */
+export const userPermissionOverrides = pgTable(
+  'user_permission_overrides',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    userId: text('user_id').notNull(),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id, { onDelete: 'cascade' }),
+    permissionOverrides: jsonb('permission_overrides')
+      .$type<Partial<RolePermissions>>()
+      .notNull()
+      .default({}),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('idx_user_perm_overrides_user_port').on(table.userId, table.portId),
+    index('idx_user_perm_overrides_user').on(table.userId),
+  ],
+);
+
+export type UserPermissionOverride = typeof userPermissionOverrides.$inferSelect;
+export type NewUserPermissionOverride = typeof userPermissionOverrides.$inferInsert;
+
 export const portRoleOverrides = pgTable(
   'port_role_overrides',
   {