Task #147: Add structured permission-change audit (users, groups, apps)

Mirrors the existing role-permission audit pattern with a unified
`permission_audit` table capturing actor, target, prev/new id sets, and
timestamp written in the same transaction as the change.

Schema & API
- New `permission_audit` table (target_kind, target_id, change_kind,
  actor_user_id, previous_ids[], new_ids[], created_at) with index on
  (target_kind, target_id, created_at).
- Transactional audit writes in routes/users.ts (POST/DELETE roles,
  PATCH groupIds), routes/groups.ts (PATCH + add/remove members for
  users/roles/apps), routes/apps.ts (POST/DELETE permissions).
- Cross-entity mirroring: when group membership changes via a group
  endpoint, a user.groups row is also written for each affected user
  (and vice versa via PATCH /users), so each entity's history is
  exhaustive regardless of which editor was used.
- Admin-only GET /users/:id/audit, /groups/:id/audit, /apps/:id/audit
  with limit/offset/actorUserId/from/to filters and the same response
  shape as role audit.
- OpenAPI types + codegen regenerated.

UI
- Reusable PermissionAuditHistory component in admin.tsx wired into
  UserGroupsEditor, GroupDetailEditor (new "history" tab), and the
  editing-app dialog. App history correctly resolves permission ids
  (NOT roles) via useListPermissions.
- Bilingual i18n keys added under admin.{users,groups,apps}.history*
  in en.json + ar.json.

Tests
- New backend tests: user-permission-audit, group-permission-audit,
  app-permission-audit (14 cases — transactional capture, GET filters
  & pagination, admin-only, 404 on unknown id, plus 2 new mirror
  tests covering cross-entity audit visibility). All pass; 35
  adjacent role/groups/users/audit-coverage tests still pass.

Notes
- replit.md updated to list `permission_audit` table.
- Restored opengraph.jpg (an unrelated stray binary diff).
- Code-review comments addressed: cross-entity asymmetry fixed via
  mirroring; opengraph.jpg restored.
- Follow-ups proposed: timeline UI improvements, cascade audit on
  delete/bulk paths, e2e UI test for History sections.

Replit-Task-Id: 4ba8c8de-8dfd-42c7-a3bc-964a1ed3a1a3

lib/api-client-react/src/generated/api.schemas.ts

@@ -910,6 +910,49 @@ export interface RolePermissionAuditList {
   nextOffset: number | null;
 }
 
+export type PermissionAuditEntryTargetKind =
+  (typeof PermissionAuditEntryTargetKind)[keyof typeof PermissionAuditEntryTargetKind];
+
+export const PermissionAuditEntryTargetKind = {
+  user: "user",
+  group: "group",
+  app: "app",
+} as const;
+
+export type PermissionAuditEntryChangeKind =
+  (typeof PermissionAuditEntryChangeKind)[keyof typeof PermissionAuditEntryChangeKind];
+
+export const PermissionAuditEntryChangeKind = {
+  userroles: "user.roles",
+  usergroups: "user.groups",
+  groupusers: "group.users",
+  grouproles: "group.roles",
+  groupapps: "group.apps",
+  apppermissions: "app.permissions",
+} as const;
+
+export interface PermissionAuditEntry {
+  id: number;
+  targetKind: PermissionAuditEntryTargetKind;
+  targetId: number;
+  changeKind: PermissionAuditEntryChangeKind;
+  previousIds: number[];
+  newIds: number[];
+  addedIds: number[];
+  removedIds: number[];
+  createdAt: string;
+  actor: AuditLogActor | null;
+}
+
+export interface PermissionAuditList {
+  entries: PermissionAuditEntry[];
+  totalCount: number;
+  limit: number;
+  offset: number;
+  /** @nullable */
+  nextOffset: number | null;
+}
+
 /**
  * @nullable
  */
@@ -1028,6 +1071,60 @@ export type DeleteGroupParams = {
   force?: boolean;
 };
 
+export type GetUserPermissionAuditParams = {
+  /**
+   * @minimum 1
+   * @maximum 200
+   */
+  limit?: number;
+  /**
+   * @minimum 0
+   */
+  offset?: number;
+  /**
+   * @minimum 0
+   */
+  actorUserId?: number;
+  from?: string;
+  to?: string;
+};
+
+export type GetGroupPermissionAuditParams = {
+  /**
+   * @minimum 1
+   * @maximum 200
+   */
+  limit?: number;
+  /**
+   * @minimum 0
+   */
+  offset?: number;
+  /**
+   * @minimum 0
+   */
+  actorUserId?: number;
+  from?: string;
+  to?: string;
+};
+
+export type GetAppPermissionAuditParams = {
+  /**
+   * @minimum 1
+   * @maximum 200
+   */
+  limit?: number;
+  /**
+   * @minimum 0
+   */
+  offset?: number;
+  /**
+   * @minimum 0
+   */
+  actorUserId?: number;
+  from?: string;
+  to?: string;
+};
+
 export type GetAdminStatsParams = {
   /**
    * Time range for trend stats. Use "custom" with from/to.

lib/api-client-react/src/generated/api.ts

@@ -49,7 +49,10 @@ import type {
   GetAdminAppOpensByAppParams,
   GetAdminAppOpensByUserParams,
   GetAdminStatsParams,
+  GetAppPermissionAuditParams,
+  GetGroupPermissionAuditParams,
   GetRolePermissionAuditParams,
+  GetUserPermissionAuditParams,
   Group,
   GroupDeletionConflict,
   GroupDetail,
@@ -63,6 +66,7 @@ import type {
   MessageWithSender,
   Notification,
   Permission,
+  PermissionAuditList,
   RegisterBody,
   ReplaceRolePermissionsBody,
   RequestUploadUrlBody,
@@ -6342,6 +6346,371 @@ export const useDeleteGroup = <
   return useMutation(getDeleteGroupMutationOptions(options));
 };
 
+/**
+ * Returns permission-change audit records for the given user, newest
+first. Mirrors the role audit endpoint shape and supports the same
+`limit`/`offset`/`actorUserId`/`from`/`to` filters. Each entry
+captures the actor (if known), the previous and new id sets, and
+the change kind (`user.roles` or `user.groups`).
+
+ * @summary List recent permission-change audit entries for a user (admin)
+ */
+export const getGetUserPermissionAuditUrl = (
+  id: number,
+  params?: GetUserPermissionAuditParams,
+) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0
+    ? `/api/users/${id}/audit?${stringifiedParams}`
+    : `/api/users/${id}/audit`;
+};
+
+export const getUserPermissionAudit = async (
+  id: number,
+  params?: GetUserPermissionAuditParams,
+  options?: RequestInit,
+): Promise<PermissionAuditList> => {
+  return customFetch<PermissionAuditList>(
+    getGetUserPermissionAuditUrl(id, params),
+    {
+      ...options,
+      method: "GET",
+    },
+  );
+};
+
+export const getGetUserPermissionAuditQueryKey = (
+  id: number,
+  params?: GetUserPermissionAuditParams,
+) => {
+  return [`/api/users/${id}/audit`, ...(params ? [params] : [])] as const;
+};
+
+export const getGetUserPermissionAuditQueryOptions = <
+  TData = Awaited<ReturnType<typeof getUserPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetUserPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getUserPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+) => {
+  const { query: queryOptions, request: requestOptions } = options ?? {};
+
+  const queryKey =
+    queryOptions?.queryKey ?? getGetUserPermissionAuditQueryKey(id, params);
+
+  const queryFn: QueryFunction<
+    Awaited<ReturnType<typeof getUserPermissionAudit>>
+  > = ({ signal }) =>
+    getUserPermissionAudit(id, params, { signal, ...requestOptions });
+
+  return {
+    queryKey,
+    queryFn,
+    enabled: !!id,
+    ...queryOptions,
+  } as UseQueryOptions<
+    Awaited<ReturnType<typeof getUserPermissionAudit>>,
+    TError,
+    TData
+  > & { queryKey: QueryKey };
+};
+
+export type GetUserPermissionAuditQueryResult = NonNullable<
+  Awaited<ReturnType<typeof getUserPermissionAudit>>
+>;
+export type GetUserPermissionAuditQueryError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary List recent permission-change audit entries for a user (admin)
+ */
+
+export function useGetUserPermissionAudit<
+  TData = Awaited<ReturnType<typeof getUserPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetUserPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getUserPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+  const queryOptions = getGetUserPermissionAuditQueryOptions(
+    id,
+    params,
+    options,
+  );
+
+  const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+    queryKey: QueryKey;
+  };
+
+  return { ...query, queryKey: queryOptions.queryKey };
+}
+
+/**
+ * Returns permission-change audit records for the given group, newest
+first. Captures changes to the group's user, role and app sets via
+the discriminator field `changeKind`.
+
+ * @summary List recent permission-change audit entries for a group (admin)
+ */
+export const getGetGroupPermissionAuditUrl = (
+  id: number,
+  params?: GetGroupPermissionAuditParams,
+) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0
+    ? `/api/groups/${id}/audit?${stringifiedParams}`
+    : `/api/groups/${id}/audit`;
+};
+
+export const getGroupPermissionAudit = async (
+  id: number,
+  params?: GetGroupPermissionAuditParams,
+  options?: RequestInit,
+): Promise<PermissionAuditList> => {
+  return customFetch<PermissionAuditList>(
+    getGetGroupPermissionAuditUrl(id, params),
+    {
+      ...options,
+      method: "GET",
+    },
+  );
+};
+
+export const getGetGroupPermissionAuditQueryKey = (
+  id: number,
+  params?: GetGroupPermissionAuditParams,
+) => {
+  return [`/api/groups/${id}/audit`, ...(params ? [params] : [])] as const;
+};
+
+export const getGetGroupPermissionAuditQueryOptions = <
+  TData = Awaited<ReturnType<typeof getGroupPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetGroupPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getGroupPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+) => {
+  const { query: queryOptions, request: requestOptions } = options ?? {};
+
+  const queryKey =
+    queryOptions?.queryKey ?? getGetGroupPermissionAuditQueryKey(id, params);
+
+  const queryFn: QueryFunction<
+    Awaited<ReturnType<typeof getGroupPermissionAudit>>
+  > = ({ signal }) =>
+    getGroupPermissionAudit(id, params, { signal, ...requestOptions });
+
+  return {
+    queryKey,
+    queryFn,
+    enabled: !!id,
+    ...queryOptions,
+  } as UseQueryOptions<
+    Awaited<ReturnType<typeof getGroupPermissionAudit>>,
+    TError,
+    TData
+  > & { queryKey: QueryKey };
+};
+
+export type GetGroupPermissionAuditQueryResult = NonNullable<
+  Awaited<ReturnType<typeof getGroupPermissionAudit>>
+>;
+export type GetGroupPermissionAuditQueryError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary List recent permission-change audit entries for a group (admin)
+ */
+
+export function useGetGroupPermissionAudit<
+  TData = Awaited<ReturnType<typeof getGroupPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetGroupPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getGroupPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+  const queryOptions = getGetGroupPermissionAuditQueryOptions(
+    id,
+    params,
+    options,
+  );
+
+  const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+    queryKey: QueryKey;
+  };
+
+  return { ...query, queryKey: queryOptions.queryKey };
+}
+
+/**
+ * Returns permission-change audit records for the given app, newest
+first. Captures changes to the set of permissions required to open
+the app (`changeKind: app.permissions`).
+
+ * @summary List recent permission-change audit entries for an app (admin)
+ */
+export const getGetAppPermissionAuditUrl = (
+  id: number,
+  params?: GetAppPermissionAuditParams,
+) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? "null" : value.toString());
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0
+    ? `/api/apps/${id}/audit?${stringifiedParams}`
+    : `/api/apps/${id}/audit`;
+};
+
+export const getAppPermissionAudit = async (
+  id: number,
+  params?: GetAppPermissionAuditParams,
+  options?: RequestInit,
+): Promise<PermissionAuditList> => {
+  return customFetch<PermissionAuditList>(
+    getGetAppPermissionAuditUrl(id, params),
+    {
+      ...options,
+      method: "GET",
+    },
+  );
+};
+
+export const getGetAppPermissionAuditQueryKey = (
+  id: number,
+  params?: GetAppPermissionAuditParams,
+) => {
+  return [`/api/apps/${id}/audit`, ...(params ? [params] : [])] as const;
+};
+
+export const getGetAppPermissionAuditQueryOptions = <
+  TData = Awaited<ReturnType<typeof getAppPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetAppPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getAppPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+) => {
+  const { query: queryOptions, request: requestOptions } = options ?? {};
+
+  const queryKey =
+    queryOptions?.queryKey ?? getGetAppPermissionAuditQueryKey(id, params);
+
+  const queryFn: QueryFunction<
+    Awaited<ReturnType<typeof getAppPermissionAudit>>
+  > = ({ signal }) =>
+    getAppPermissionAudit(id, params, { signal, ...requestOptions });
+
+  return {
+    queryKey,
+    queryFn,
+    enabled: !!id,
+    ...queryOptions,
+  } as UseQueryOptions<
+    Awaited<ReturnType<typeof getAppPermissionAudit>>,
+    TError,
+    TData
+  > & { queryKey: QueryKey };
+};
+
+export type GetAppPermissionAuditQueryResult = NonNullable<
+  Awaited<ReturnType<typeof getAppPermissionAudit>>
+>;
+export type GetAppPermissionAuditQueryError = ErrorType<ErrorResponse>;
+
+/**
+ * @summary List recent permission-change audit entries for an app (admin)
+ */
+
+export function useGetAppPermissionAudit<
+  TData = Awaited<ReturnType<typeof getAppPermissionAudit>>,
+  TError = ErrorType<ErrorResponse>,
+>(
+  id: number,
+  params?: GetAppPermissionAuditParams,
+  options?: {
+    query?: UseQueryOptions<
+      Awaited<ReturnType<typeof getAppPermissionAudit>>,
+      TError,
+      TData
+    >;
+    request?: SecondParameter<typeof customFetch>;
+  },
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+  const queryOptions = getGetAppPermissionAuditQueryOptions(
+    id,
+    params,
+    options,
+  );
+
+  const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+    queryKey: QueryKey;
+  };
+
+  return { ...query, queryKey: queryOptions.queryKey };
+}
+
 /**
  * @summary Get home screen stats
  */