create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/mithaq/src/roles/statements.ts

@@ -0,0 +1,13 @@
+/**
+ * The keys this project adds beside a kayan's own operations, by kayan. Each
+ * joins the catalog as `<kayan>.<key>`, held by a role like any operation's key,
+ * and the dashboard's role form offers it among that kayan's operations,
+ * labelled by the kayan's copy under `operations.<key>`. It is plain data,
+ * imported by the server and by the role form alike.
+ */
+export const projectStatements = {
+  // add-on: courses
+  // Every seat of the organization rather than the actor's own.
+  enrollments: ['others'],
+  // end add-on: courses
+} as const satisfies Record<string, readonly string[]>

package/template/templates/mithaq/src/roles/system-roles.ts

@@ -0,0 +1,16 @@
+// The subpath, so a page piece reading the fixed roles' labels loads no server code.
+import { backofficeRoles } from '../mithaq/auth/backoffice-roles.ts'
+import type { SystemRoles } from 'mithaq'
+import { tenantRoles } from './tenant-roles.ts'
+
+export { tenantRoles }
+
+/**
+ * Every role this project ships, the backoffice's and the tenants', which is what
+ * the access target takes whole: it holds a slug's keys wherever the project's
+ * reader answers it. The backoffice roles are the auth setup's, because the column
+ * they live on is Better Auth's own `user.role` and the admin plugin's roles are
+ * built from the same lists. The reader answers them in the backoffice app alone,
+ * and an assignment never names one.
+ */
+export const systemRoles = { ...backofficeRoles, ...tenantRoles } as const satisfies SystemRoles

package/template/templates/mithaq/src/roles/tenant-access.ts

@@ -0,0 +1,260 @@
+import { onBackoffice, backofficeApp, backofficeRoles, backofficeURL } from '../mithaq/auth/index.ts'
+import { secret } from '../mithaq/auth/backoffice-roles.ts'
+import { actorPermissions, actorRoles, authActor, userRefs, type Held, type RowTable, type Store } from 'mithaq'
+// add-on: roles
+import { isOwner, OWNER_ROLE } from './grants.ts'
+// end add-on: roles
+
+/**
+ * What a row may name on the actor: `user.<key>` in any kayan's row is checked
+ * against these keys. The active organization is a string because a row that
+ * resolves it to anything else throws rather than filtering.
+ */
+export type OrganizationActor = {
+  activeOrganizationId: string
+  /** The person's own id, which a field defaults to when the row is the actor's own. */
+  id: string
+  /**
+   * Better Auth's own `member.role`: governance only (settings, members,
+   * invitations, the provider's `owner` override). Optional because a local-auth
+   * actor is no organization's member.
+   */
+  memberRole?: string
+  /** The real person behind an impersonated session, so the audit handler names who really made the write. */
+  impersonatedBy?: string
+  organizationIds?: readonly string[]
+}
+
+/**
+ * The backoffice administrator's slug. Backoffice roles live on Better Auth's
+ * `user.role`, never in a tenant's assignment: `assignedRoles` drops any such
+ * slug there, because the access target holds a slug's keys only where this
+ * reader answers it.
+ */
+export const BACKOFFICE = 'super_admin'
+
+/**
+ * The backoffice screen, the only place the backoffice roles answer. The app decides
+ * this, never the request.
+ */
+export const BACKOFFICE_SCREEN = 'backoffice'
+
+/**
+ * The kayan whose session carries the backoffice column, the one `auth.admin`
+ * names. A build may run several Better Auth instances, and only this one's
+ * `user.role` is the layer above every tenant.
+ */
+const BACKOFFICE_KAYAN = 'user'
+
+/**
+ * Backoffice roles read every tenant's rows and write none; staff change a
+ * tenant's data only by impersonating a member, which is audited. Every write is
+ * an explicit `false`, because a slug a table leaves out still takes the `'*'`
+ * row, which opens every write. The row opens the door and the keys decide who
+ * walks through it.
+ */
+const readOnly = { create: false, read: true, update: false, delete: false } as const
+
+/** The read-only row under every backoffice role, which every row table of this project spreads in. */
+export const backofficeReads = Object.fromEntries(Object.keys(backofficeRoles).map((slug) => [slug, readOnly])) as {
+  readonly [Slug in keyof typeof backofficeRoles]: typeof readOnly
+}
+
+/**
+ * Every operation refused under every backoffice role, spread in place of
+ * `backofficeReads` by tables the backoffice does not read, such as the settings
+ * global and the audit log.
+ */
+const closed = { create: false, read: false, update: false, delete: false } as const
+export const backofficeClosed = Object.fromEntries(Object.keys(backofficeRoles).map((slug) => [slug, closed])) as {
+  readonly [Slug in keyof typeof backofficeRoles]: typeof closed
+}
+
+/**
+ * The accessor every row of this project is written with. The actor is typed
+ * here once because a kayan's table is written before the language is imported
+ * into its file.
+ */
+export const user = userRefs<OrganizationActor>()
+
+/**
+ * The organization the actor's session has active, read off the trusted
+ * snapshot and checked against the provider's own list, or `null`.
+ */
+export const currentOrganization = (user: unknown) => {
+  const trusted = authActor(user)
+  if (!trusted || trusted.strategy !== 'better-auth') return null
+  const active = trusted.activeOrganizationId
+  const organizations = trusted.organizations
+  if (typeof active !== 'string' || !Array.isArray(organizations)) return null
+  return organizations.some((organization) => organization.id === active) ? active : null
+}
+
+/**
+ * The backoffice rows of the tenant-owned kayan: `backofficeReads` minus the
+ * columns `secret` names. A row's field list closes a column whatever keys the
+ * actor holds, and a column an actor may not read is no filter either.
+ */
+const readsNoSecret = { ...readOnly, fields: ['*', ...secret.map((key) => `!${key.slice(key.indexOf('.fields.') + '.fields.'.length)}`)] as readonly string[] }
+const secretClosed = Object.fromEntries(Object.keys(backofficeRoles).map((slug) => [slug, readsNoSecret])) as {
+  readonly [Slug in keyof typeof backofficeRoles]: typeof readsNoSecret
+}
+
+/**
+ * The rows every tenant-owned kayan inherits. The organization is core's: a
+ * read, a write and a reference reach the session's active organization alone,
+ * whatever a row here answers. `'*'` is the row every actor assigned a role
+ * takes beside its roles' own, so a custom role's keys decide what it reaches;
+ * an actor assigned no role takes no row and is denied.
+ *
+ * No row here names `permissions`: what a role holds is the access target's
+ * business, and a second answer here would let a role row widen.
+ */
+export const tenantAccess = {
+  '*': { create: true, read: true, update: true, delete: true },
+  // add-on: courses
+  /**
+   * The one row keyed on a system slug, and it narrows: an instructor teaches and
+   * never removes a row. Every operation is named in full, because a missing one
+   * reads as `false` and a `false` in any applicable row wins.
+   */
+  instructor: { create: true, read: true, update: true, delete: false },
+  // end add-on: courses
+  ...secretClosed,
+} as const satisfies RowTable
+
+/**
+ * The roles a kayan's rows are read through; its parameter also types `user` for
+ * every row this project writes. Slugs come from the access target for the
+ * active organization, off the trusted snapshot, so an object naming its own
+ * roles is no one.
+ */
+export const assignedRoles = (actor: OrganizationActor): readonly string[] => {
+  if (!authActor(actor)) return []
+  // The backoffice app answers the backoffice roles alone and the tenant app the
+  // membership's roles alone, never unioned, so neither adds keys on the other's
+  // screens. Which app serves the request is the app's own fact, never the request's.
+  if (onBackoffice()) return backofficeRolesOf(actor)
+  if (!currentOrganization(actor)) return []
+  const assigned = (actorRoles(actor) ?? []).filter((slug) => !Object.hasOwn(backofficeRoles, slug))
+  // add-on: roles
+  // The slugs are the `memberRoles` kayan's, and `member.role` grants one thing
+  // only: an owner always holds `administrator` in its tenant, so the role that
+  // manages roles is never lost.
+  if (isOwner(authActor(actor)?.memberRole) && !assigned.includes(OWNER_ROLE)) return [...assigned, OWNER_ROLE]
+  // end add-on: roles
+  return assigned
+}
+
+/**
+ * Whether `assignedRoles` answers this actor `super_admin`, which only the
+ * backoffice app does. It is the administrator of `auth.admin`, the one answer
+ * local auth's `_verified` writes ask, and the reader and writer of local accounts.
+ */
+export const superAdmin = ({ user }: { user: unknown }) => assignedRoles(user as OrganizationActor).includes(BACKOFFICE)
+
+/**
+ * Every operation refused to every actor, the administrator included, for the
+ * tables Better Auth alone reads and writes through its adapter. Without it those
+ * kayan would fall to the administrator's default access, and a super admin would
+ * read every session token and password hash.
+ */
+export const providerOnly = { create: () => false, read: () => false, update: () => false, delete: () => false } as const
+
+/**
+ * The backoffice roles this actor holds on Better Auth's `user.role`, whichever app
+ * asks. Several are comma-separated, and only a backoffice role's name counts.
+ *
+ * The column is read off the trusted snapshot, and only from the admin kayan's
+ * session on a Better Auth strategy: a build may run several instances that all
+ * write `user.role`, and local auth spreads its kayan's row onto the actor, so a
+ * `role` column there would otherwise hand someone a backoffice role.
+ */
+export const backofficeRolesOf = (actor: unknown): string[] => {
+  const trusted = authActor(actor)
+  if (!trusted || trusted.strategy !== 'better-auth' || trusted.collection !== BACKOFFICE_KAYAN || typeof trusted.role !== 'string') return []
+  return [...new Set(trusted.role.split(',').map((slug) => slug.trim()).filter((slug) => Object.hasOwn(backofficeRoles, slug)))]
+}
+
+/**
+ * Where the tenant app's header links the backoffice app, for an actor whose
+ * backoffice roles hold `screen.backoffice`; nothing otherwise. It is a link and
+ * grants nothing: the backoffice app's own server decides entry. A project that
+ * serves no backoffice app links nowhere.
+ */
+export const backofficeEntry = (actor: unknown): string | undefined => {
+  if (onBackoffice() || !backofficeApp) return undefined
+  const enters = backofficeRolesOf(actor).some((slug) => {
+    const held = backofficeRoles[slug as keyof typeof backofficeRoles].permissions
+    return held === '*' || (held as readonly string[]).includes(`screen.${BACKOFFICE_SCREEN}`)
+  })
+  return enters ? new URL(`/${BACKOFFICE_SCREEN}`, backofficeURL).href : undefined
+}
+
+/**
+ * The keys a provider kayan's columns are graded by, which `rows()` takes as its
+ * `holds`: in the tenant app the id and the name alone, and only where the actor
+ * holds their keys; in the backoffice app the actor's own keys. An actor holding no
+ * key reads no column, since an empty set grades every column closed where
+ * `undefined` would grade none.
+ */
+export const namesInTenant = (kayan: string) => (actor: unknown): Held => {
+  const held = actorPermissions(actor)
+  if (onBackoffice()) return held
+  return new Set(['id', 'name'].map((field) => `${kayan}.fields.${field}`).filter((key) => held === true || held?.has(key) === true))
+}
+
+/**
+ * Whom a role reads among its organization's people when it holds no
+ * `member.find`: the members assigned one of the roles named here, beside
+ * itself. A role left out, a custom role included, reads itself alone, so a
+ * key to read people never by itself opens the staff to a portal role.
+ */
+export const peopleAudience: Readonly<Record<string, readonly string[]>> = {
+  // add-on: courses
+  // The students it enrols, never the staff.
+  instructor: ['student'],
+  // end add-on: courses
+}
+
+/**
+ * The read the person's own rows are ANDed with, so it narrows and never widens:
+ * the members of the organization the actor's session has active, read off the
+ * store, all of them to a holder of `member.find`, who lists them through the
+ * provider anyway, and otherwise the actor and its roles' `peopleAudience`. The
+ * organization is the trusted snapshot's, so a claim is no one's.
+ */
+export const membersOf = (store: Pick<Store, 'find'>) => async ({ user: actor }: { user: unknown }) => {
+  // A backoffice role reads every person in the backoffice app; the rows answer who holds one.
+  if (onBackoffice()) return true
+  const active = currentOrganization(actor)
+  if (!active) return false
+  const all = { limit: 0, page: 1, sort: { field: 'id', direction: 'asc' } } as const
+  const members = await store.find({ kayan: 'member', args: { ...all, where: { organizationId: { equals: active } } } })
+  const ids = members.docs.map((row) => row.userId).filter((id): id is string => typeof id === 'string')
+  const held = actorPermissions(actor)
+  if (held === true || held?.has('member.find')) return ids.length ? { id: { in: ids } } : false
+  const seen = new Set([authActor(actor)?.id])
+  // add-on: roles
+  // A custom role's name is a tenant's to write, so one named `constructor` reads no inherited key.
+  const audience =[...new Set(assignedRoles(actor as OrganizationActor).flatMap((slug) => (Object.hasOwn(peopleAudience, slug) ? peopleAudience[slug]! : [])))]
+  if (audience.length) {
+    const assigned = await store.find({ kayan: 'memberRoles', args: { ...all, where: { organization: { equals: active }, role: { in: audience } } } })
+    for (const row of assigned.docs) seen.add(row.user)
+  }
+  // end add-on: roles
+  // An assignment can outlive its membership, so only a current member is seen.
+  const reached = ids.filter((id) => seen.has(id))
+  return reached.length ? { id: { in: reached } } : false
+}
+
+/**
+ * Whether an actor reads past what a kayan's own read narrows for roles not
+ * holding `key`: in the backoffice app, whose staff read every tenant's rows whole,
+ * or in a tenant, holding that key. The courses add-on narrows archived courses,
+ * sessions and covers of unreadable courses and other people's seats this way.
+ */
+export const readsPast = (actor: unknown, key: string) => {
+  const held = actorPermissions(actor)
+  return onBackoffice() || held === true || held?.has(key) === true
+}

package/template/templates/mithaq/src/roles/tenant-roles.ts

@@ -0,0 +1,321 @@
+import type { SystemRoles } from 'mithaq'
+// without add-on: roles
+// import { defaultMemberRoles } from './default-member-roles.ts'
+// end without add-on: roles
+
+// add-on: courses
+/** A session's columns but its `enrollments`, which the registrar and the instructor read alike. */
+const sessionColumns = [
+  'sessions.fields.id',
+  'sessions.fields.createdAt',
+  'sessions.fields.updatedAt',
+  'sessions.fields.organization',
+  'sessions.fields.course',
+  'sessions.fields.startsAt',
+  'sessions.fields.capacity',
+  'sessions.fields.venue',
+  'sessions.fields.format',
+  'sessions.fields.archived',
+  'sessions.fields.archiveReason',
+  'sessions.fields.details',
+] as const
+
+/**
+ * What the portal's catalogue and course page read beside a course's own columns, for its roles alike: the
+ * sessions with the seats each has left, and the names of the tags it carries.
+ */
+const catalogueReads = [
+  'courses.findWithSessions',
+  'courses.fields.tags',
+  'courses.fields.selfEnroll',
+  'tags.find',
+  'tags.findByID',
+  'tags.fields.id',
+  'tags.fields.name',
+] as const
+
+// add-on: settings
+/** Whether the portal is closed for maintenance, and where to write, which the portal's foot reads for its roles alike. */
+const portalSettings = ['settings.findOne', 'settings.fields.maintenance', 'settings.fields.contactEmail'] as const
+// end add-on: settings
+
+/** A course's cover, read and never changed, which the portal's roles read alike. */
+const coverReads = [
+  'media.find',
+  'media.findByID',
+  'media.fields.alt',
+  'media.fields.createdAt',
+  'media.fields.filename',
+  'media.fields.filesize',
+  'media.fields.height',
+  'media.fields.id',
+  'media.fields.key',
+  'media.fields.mimeType',
+  'media.fields.storage',
+  'media.fields.organization',
+  'media.fields.updatedAt',
+  'media.fields.width',
+] as const
+// end add-on: courses
+
+/**
+ * The roles this project ships to every tenant, written in code and never a
+ * row: the access target takes them whole and reads what each holds from here.
+ * A page lists them from here too, which is why this file imports no server
+ * code.
+ *
+ * A slug here is the whole vocabulary of role names: a row table may be keyed on
+ * one of them or on `'*'` and on nothing else, and `buildAsas` refuses a key
+ * that is not in this project's catalog exactly as it does for a row's own.
+ *
+ * The backoffice roles, `super_admin` among them, are not here: they are staff
+ * above every tenant, held on Better Auth's `user.role`, and the access target
+ * holds their keys in the backoffice app alone. Inside a tenant every actor, a
+ * `super_admin` included, holds what its membership's roles hold and nothing
+ * more.
+ */
+export const tenantRoles = {
+  // add-on: roles
+  // These are business roles and never governance, and the `roles` kayan holds
+  // a tenant's own roles beside them; an assignment names one of either. Better
+  // Auth's own `member.role`, which holds `owner`, `admin` or `member`, stays
+  // what the provider uses for settings, members and invitations, and nothing
+  // here reads it. Sharing one comma-joined column would inherit the provider's
+  // own open comma-in-a-role-name bug.
+  //
+  // A new organization's creator is assigned `administrator` while the
+  // organization is being created, by the hook the template wires into the
+  // provider, so a fresh tenant has a root granter from its first moment. That
+  // row is written straight through the store, because a managed create is
+  // graded against the actor making it and the creator is in no organization
+  // until that route puts it in one.
+  /**
+   * The tenant's root granter: every key of the project, which is what lets it
+   * author a custom role at all. `'*'` holds every screen's key too, so it
+   * enters the dashboard and the portal alike. It never reaches the backoffice
+   * app, where the reader answers no membership role at all.
+   * `grantedPermissions` returns early on a granter holding everything, so this
+   * role and no other may hand out a key it will never use itself.
+   */
+  administrator: {
+    label: { ar: 'مدير', en: 'Administrator' },
+    permissions: '*',
+  },
+  /** Runs the catalogue in the dashboard: the courses, their sessions and the tags on them. */
+  registrar: {
+    label: { ar: 'مسجل', en: 'Registrar' },
+    permissions: [
+      'screen.dashboard',
+      // add-on: courses
+      'courses.create',
+      'courses.find',
+      'courses.count',
+      'courses.findByID',
+      'courses.update',
+      // A course leaves the catalogue and comes back through its own operations, each with its reason.
+      'courses.archive',
+      'courses.unarchive',
+      'courses.fields.archived',
+      'courses.fields.archiveReason',
+      'courses.fields.createdAt',
+      'courses.fields.cover',
+      'courses.fields.currency',
+      'courses.fields.details',
+      'courses.fields.fee',
+      'courses.fields.id',
+      'courses.fields.tags',
+      'courses.fields.organization',
+      'courses.fields.title',
+      'courses.fields.updatedAt',
+      'courses.fields.selfEnroll',
+      // Whether a course is a draft, its versions and the restore of one: the
+      // registrar edits the catalogue, so it reads a course's history and puts
+      // an older copy back.
+      'courses.fields._status',
+      'courses.findVersions',
+      'courses.findVersionByID',
+      'courses.restoreVersion',
+      'sessions.create',
+      'sessions.find',
+      'sessions.count',
+      'sessions.findByID',
+      'sessions.update',
+      // The columns of each kayan it holds an operation of, without which every
+      // read of it is refused for its fields and its pages draw nothing. Not a
+      // session's `enrollments`, which reads a kayan this role does not.
+      ...sessionColumns,
+      // end add-on: courses
+      'tags.find',
+      'tags.count',
+      'tags.findByID',
+      'tags.fields.id',
+      'tags.fields.createdAt',
+      'tags.fields.updatedAt',
+      'tags.fields.organization',
+      'tags.fields.name',
+      // add-on: media
+      // The images a course's cover is picked from, which it uploads,
+      // re-describes and deletes once no course points at one.
+      'media.create',
+      'media.find',
+      'media.count',
+      'media.findByID',
+      'media.update',
+      'media.delete',
+      'media.fields.alt',
+      'media.fields.createdAt',
+      'media.fields.filename',
+      'media.fields.filesize',
+      'media.fields.height',
+      'media.fields.id',
+      'media.fields.key',
+      'media.fields.mimeType',
+      'media.fields.storage',
+      'media.fields.organization',
+      'media.fields.updatedAt',
+      'media.fields.width',
+      // end add-on: media
+      // add-on: audit-log
+      // The activity panel on each edit page it opens: the entries of the
+      // kayan it lists, each change graded by the column's own key above.
+      'auditLog.find',
+      'auditLog.fields.id',
+      'auditLog.fields.createdAt',
+      'auditLog.fields.kayan',
+      'auditLog.fields.record',
+      'auditLog.fields.operation',
+      'auditLog.fields.actor',
+      'auditLog.fields.impersonatedBy',
+      'auditLog.fields.changes',
+      // end add-on: audit-log
+    ],
+  },
+  // add-on: courses
+  /**
+   * Teaches: reads the catalogue and enrols. It holds no `courses.archive`. It
+   * works in the portal, which draws the courses and the enrolments, and never
+   * enters the dashboard.
+   */
+  instructor: {
+    label: { ar: 'مدرس', en: 'Instructor' },
+    permissions: [
+      'screen.portal',
+      'courses.find',
+      'courses.count',
+      'courses.findByID',
+      'courses.fields.archived',
+      'courses.fields.createdAt',
+      'courses.fields.cover',
+      'courses.fields.details',
+      'courses.fields.id',
+      'courses.fields.organization',
+      'courses.fields.title',
+      'courses.fields.updatedAt',
+      // What the portal's catalogue draws on a course's card and its page.
+      'courses.fields.summary',
+      'courses.fields.fee',
+      'courses.fields.currency',
+      'courses.fields.delivery',
+      // It reads published courses alone, and whether one is published with them.
+      'courses.fields._status',
+      'enrollments.create',
+      'enrollments.find',
+      'enrollments.count',
+      'enrollments.findByID',
+      // Every seat of its organization, not only its own
+      'enrollments.others',
+      // An enrollment's columns but the soft-delete mark, which the runner
+      // writes, and a session's, which the enrollment's picker and cell read
+      'enrollments.fields.id',
+      'enrollments.fields.createdAt',
+      'enrollments.fields.updatedAt',
+      'enrollments.fields.organization',
+      'enrollments.fields.session',
+      'enrollments.fields.student',
+      'sessions.find',
+      'sessions.count',
+      'sessions.findByID',
+      ...sessionColumns,
+      // The students of its organization by their id and name alone, which the
+      // enrollment drawer's student picker lists and an enrollment's student is
+      // titled by: `peopleAudience` in `tenant-access.ts` names whom it reads.
+      'user.find',
+      'user.count',
+      'user.findByID',
+      'user.fields.id',
+      'user.fields.name',
+      ...coverReads,
+      ...catalogueReads,
+      // add-on: settings
+      ...portalSettings,
+      // end add-on: settings
+    ],
+  },
+  /**
+   * Takes the courses: reads the catalogue in the portal, a course's cover
+   * with it, and its own enrollments with the sessions they name. Not the
+   * access code, which a course hands out to whoever it chooses, nor the
+   * archive reason or the notifications, which are staff's.
+   *
+   * A role's keys reach every row of the organization, so the enrollment keys
+   * alone would hand a student every other student's seat. The enrollments'
+   * own access narrows them to the student's own seats, since it holds no
+   * `enrollments.others`, and the sessions' to those of the courses it reads.
+   * It takes a seat for itself alone, in a course that lets its students enroll
+   * themselves and before the session starts, and gives one back before then:
+   * the enrollments' own steps hold it to that. It changes no seat.
+   */
+  student: {
+    label: { ar: 'طالب', en: 'Student' },
+    permissions: [
+      'screen.portal',
+      'courses.find',
+      'courses.count',
+      'courses.findByID',
+      'courses.fields.id',
+      'courses.fields.createdAt',
+      'courses.fields.updatedAt',
+      'courses.fields.organization',
+      'courses.fields.title',
+      'courses.fields.summary',
+      'courses.fields.details',
+      'courses.fields.cover',
+      'courses.fields.fee',
+      'courses.fields.currency',
+      'courses.fields.level',
+      'courses.fields.delivery',
+      'courses.fields.audience',
+      'courses.fields.opensOn',
+      'courses.fields.archived',
+      'courses.fields._status',
+      'enrollments.find',
+      'enrollments.count',
+      'enrollments.findByID',
+      'enrollments.create',
+      'enrollments.delete',
+      'enrollments.fields.id',
+      'enrollments.fields.createdAt',
+      'enrollments.fields.updatedAt',
+      'enrollments.fields.organization',
+      'enrollments.fields.session',
+      // Itself, which its own create fills and every seat it reads names.
+      'enrollments.fields.student',
+      // The sessions its seats name, which the enrollment's session cell draws
+      // by course and start.
+      'sessions.find',
+      'sessions.count',
+      'sessions.findByID',
+      ...sessionColumns,
+      ...coverReads,
+      ...catalogueReads,
+      // add-on: settings
+      ...portalSettings,
+      // end add-on: settings
+    ],
+  },
+  // end add-on: courses
+  // end add-on: roles
+  // without add-on: roles
+  // ...defaultMemberRoles,
+  // end without add-on: roles
+} as const satisfies SystemRoles

package/template/templates/mithaq/src/steps/expected-updated-at.ts

@@ -0,0 +1,41 @@
+// Refuses an update when the row changed after the caller read it. A kayan opts in by
+// widening its update input and listing the step before the store step:
+//
+//   update: {
+//     input: ({ update }) => update.extend({ expectedUpdatedAt: z.date() }),
+//     steps: ({ steps }) => [expectedUpdatedAt, steps.update],
+//   },
+//
+// Use `z.date()`: a string or `null` would not be a moment and would answer a misleading 409.
+// Listing the step without widening the input protects nothing, since the strict update
+// shape refuses the key by name.
+//
+// The compare is against `ctx.dataBefore`, loaded under the update's own row lock inside its
+// transaction, so on a store that honours the lock a second writer waits and no write lands
+// between the compare and the store step. A store that ignores the lock lets both through.
+//
+// updateMany runs this once per row with no instant per row: a kayan whose input requires the
+// key refuses every updateMany, and one that leaves it optional runs the bulk unguarded.
+//
+// A kayan with no `updatedAt` field has nothing to compare, so listing the step on it throws.
+//
+// A project that copies this step adds the `error.conflict.stale` copy key in every locale.
+import { conflict, type Ctx } from 'mithaq'
+
+export const expectedUpdatedAt = (ctx: Ctx<{ expectedUpdatedAt?: Date | string }>): Ctx => {
+  if (!('updatedAt' in ctx.kayan.fields)) {
+    throw new Error(`Kayan "${ctx.kayan.name}" lists expectedUpdatedAt but has no updatedAt field, so the step cannot guard it. Add defaultTimestampFields or remove the step.`)
+  }
+  const { expectedUpdatedAt: expected } = ctx.data
+  const held = ctx.dataBefore?.updatedAt
+  if (expected === undefined || held === undefined) return ctx
+  if (new Date(expected).getTime() !== new Date(held as Date).getTime()) {
+    throw conflict({
+      message: `Kayan "${ctx.kayan.name}" row changed after it was read, so it is not updated. Read it again and send the change on the row as it is.`,
+      key: 'error.conflict.stale',
+      params: { kayan: ctx.kayan.name },
+    })
+  }
+  return ctx
+}
+// mithaq-admin 0.0.0 10cc4a57db299d48c4fd53314ed42e02fc04b0464a7fa8a0c512cefc7ccb2b82