Permission templates: link users to templates so template edits update their access

Objective

• Let companies assign users to a permission template (per company membership) so that editing the template once updates access for everyone linked to it—instead of re-opening every user after each policy change.
• Reduce operational friction as teams grow: role changes (new permissions, revocations) should not require manual per-user checkbox updates across Admin Attik and company user management.

Background

• Permission templates today are reusable presets stored in permissionTemplate (attik-backend/src/models/permissionTemplateSchema.ts) and managed under Admin → Instance Management → Permission Templates (attik-frontend/src/app/admin/settings/instance-management/permission-templates/).
• When an admin picks a template in the UI (PermissionPresetSelect.tsx), the app copies template.permissions into the edit form only (onApplyPermissions(t.permissions)); saving writes that array to the membership or global permissions endpoint. There is no stored association between a user/membership and a template id.
• Runtime authorization reads permissions from the membership and user documents (membership.permissions in membershipSchema.ts, user.permissions / user.adminPermissions in userSchema.ts)—for example route gates in instanceManagement.ts, permissions.ts, and hasAdminPerm.ts for Attik admin permissions. Templates are not consulted at check time.
• Updating a template (PATCH instance-management/permission-templates/:templateId in instanceManagement.ts) only changes the template document; no users or memberships are updated.
• The same preset pattern appears in company user management (attik-frontend/src/app/tools/settings/users/[id]/DataForm.tsx) and Admin instance user management (UserEditClient.tsx — global permissions and per-membership forms).
• Product expectation from growing customers: changing a template (e.g. adding a permission for a new feature) should propagate to all users “on” that template without touching each account individually.

Scope

Backend

• attik-backend/src/models/permissionTemplateSchema.ts — template definition (permissions, type standard/brand, _companyIds).
• attik-backend/src/models/membershipSchema.ts — today stores permissions: string[] only; decision needed whether assignment is membership-scoped (likely) via a new field (e.g. template reference + optional override mode) or sync-on-save only.
• attik-backend/src/routes/instanceManagement.ts — template CRUD (GET/POST/PATCH/DELETE permission-templates), POST /users/:userId/global-permissions, user admin permissions patch; any template-update propagation or resolve-at-read logic would touch this area.
• attik-backend/src/routes/membership.ts — membership PATCH for per-company permissions; session cache invalidation via invalidateUserSessionCache after permission changes.
• attik-backend/src/routes/permissions.ts — lists templates for callers with settings-admin (company settings context).
• Attik admin permissions (user.adminPermissions, AdminPermissionsSection.tsx) are separate from company permission templates today—decision needed whether admin template linking is in scope or only company membership templates.

Frontend

• attik-frontend/src/components/permissions/PermissionPresetSelect.tsx — “Saved templates” dropdown applies a one-time copy; UX may need linked vs custom modes and visible assignment state.
• Admin: PermissionTemplatesClient.tsx, UserEditClient.tsx (GlobalPermissionsForm, MembershipPermissionsForm).
• Company tools: attik-frontend/src/app/tools/settings/users/[id]/DataForm.tsx — membership permissions + template picker.
• Decision needed: What admins see when a template changes (silent update vs notification vs “review affected users”), and whether removing a permission from a template removes it from linked users.

Product / architecture (decisions for implementer)

• Linked assignment: User/membership follows a template id; template PATCH updates effective permissions (resolve at read or sync writes).
• Sync on template save: Store template id on memberships that used it; background or inline update of membership.permissions when template changes (requires tracking assignments going forward + migration story for existing users).
• Hybrid: Linked (follow template) vs Custom (snapshot, no auto-sync); optional per-membership overrides—phase 2 if needed.
• Migration: Existing users have copied permission arrays with no template id—decision needed on backfill, opt-in linking, or grandfathered custom-only.
• Brand templates: _companyIds scoping on templates should still govern which templates appear per company when assigning.

Investigation outcomes (acceptance)

• [ ] Admin can assign a membership (and/or global permissions flow if in scope) to a template in a way that is persisted, not only a form preset.
• [ ] Editing a template’s permission list updates all linked memberships without manual per-user saves.
• [ ] Permission checks used in app routes continue to enforce access correctly after template propagation (session/cache invalidation considered).
• [ ] Behavior defined and documented for: permission removed from template, user previously custom-edited after apply, template deleted.
• [ ] Company user management and Admin instance user management surfaces stay consistent.

References

• attik-backend/src/models/permissionTemplateSchema.ts
• attik-backend/src/models/membershipSchema.ts
• attik-backend/src/routes/instanceManagement.ts
• attik-backend/src/routes/membership.ts
• attik-frontend/src/components/permissions/PermissionPresetSelect.tsx
• attik-frontend/src/app/admin/settings/instance-management/user-management/[userId]/UserEditClient.tsx
• attik-frontend/src/app/tools/settings/users/[id]/DataForm.tsx