create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/features/media/media/ui/preview.tsx

@@ -0,0 +1,143 @@
+// What the `media` kayan draws of its own files: the image beside its edit
+// form, the list's thumbnail and size cells, and the page a new image is made
+// on. Each reads the row's computed `url` and `thumbnailURL`, so a file is
+// fetched through the file route and the row's access decides. A new file is
+// made in the registry's upload dialog, which sends the bytes before the row
+// is made.
+import { useRef, useState } from 'react'
+import { Download, Upload } from 'lucide-react'
+import type { CellProps, ComponentProps, Row } from 'mithaq/admin'
+import { useAccess, useClient, useLocale, useRecord, useScreen } from 'mithaq/admin/react'
+import { locales } from '@/copy.ts'
+import { Button, buttonVariants } from '@/components/ui/button'
+import { FileThumb, FileValue, UploadDialog, sizeOf } from 'mithaq-admin/upload.tsx'
+import { AppShell } from '@asas/mithaq/ui/app-shell.tsx'
+
+/** The `filesize` column: the size as a person reads it, never the raw bytes, in the upload dialog's own units. */
+export function FileSize({ value }: CellProps) {
+  const { locale } = useLocale()
+  return typeof value === 'number' ? <span className="whitespace-nowrap">{sizeOf(value, locale)}</span> : null
+}
+
+/**
+ * The `filename` column: the image's thumbnail before its name. The name
+ * keeps at least seven rem and wraps onto a second line before it is cut,
+ * between words where it has them and anywhere only where it must, so
+ * on a phone the table gives the column room for it rather than squeezing it
+ * to "co…" beside the thumbnail.
+ */
+export function FileName({ value, row }: CellProps) {
+  const { t, locale } = useLocale()
+  const name = String(value ?? '')
+  return (
+    <span className="inline-flex min-w-0 items-center gap-2">
+      <FileThumb row={row} t={t} locale={locale} size="xs" />
+      <span className="line-clamp-2 min-w-28 [overflow-wrap:anywhere]" dir="auto" title={name}>{name}</span>
+    </span>
+  )
+}
+
+const useEditHref = () => {
+  const { path, kayan } = useScreen()
+  return (id: unknown) => `${path}${kayan.media?.pages.edit?.path.replace(':id', encodeURIComponent(String(id)))}`
+}
+
+/** The upload dialog over this kayan, which opens the new image's page once it is made. */
+function NewImageDialog({ open, onOpenChange }: { open: boolean; onOpenChange: (open: boolean) => void }) {
+  const { t, locale } = useLocale()
+  const { kayan } = useScreen()
+  const client = useClient()
+  const editHref = useEditHref()
+  // The dialog closes itself once the row is made, and that close is no
+  // Cancel: the new image's page is already opening.
+  const done = useRef(false)
+  return kayan.media ? (
+    <UploadDialog
+      open={open}
+      onOpenChange={(next) => done.current || onOpenChange(next)}
+      target={kayan.media}
+      client={client}
+      t={t}
+      locale={locale}
+      locales={locales}
+      onDone={(row: Row) => {
+        done.current = true
+        window.location.assign(editHref(row.id))
+      }}
+    />
+  ) : null
+}
+
+/**
+ * The image beside its edit form, and above it on a phone, where the record
+ * layout puts a side marked `data-lead` first: the image itself, its size, a
+ * link that downloads it, and Replace file. A file never changes once it is
+ * made, so Replace file uploads a new image and opens it, and this one stays,
+ * with whatever points at it, until it is deleted.
+ */
+export function MediaPreview() {
+  const { t, locale } = useLocale()
+  const access = useAccess()
+  const row = useRecord()
+  const [replacing, setReplacing] = useState(false)
+  if (!row) return null
+  const creates = access.collections?.media?.create === true
+  const url = typeof row.url === 'string' ? row.url : undefined
+  return (
+    <div data-media-preview="" data-lead="" className="grid justify-items-start gap-3">
+      <FileValue row={row} t={t} locale={locale} />
+      {typeof row.filesize === 'number' ? <p className="text-muted-foreground text-sm">{sizeOf(row.filesize, locale)}</p> : null}
+      <div className="flex flex-wrap gap-2">
+        {url ? (
+          <a href={url} download={typeof row.filename === 'string' ? row.filename : ''} data-media-download="" className={buttonVariants({ variant: 'outline', size: 'sm' })}>
+            <Download className="size-4" aria-hidden />
+            {t('media.download', 'Download')}
+          </a>
+        ) : null}
+        {creates ? (
+          <Button type="button" variant="outline" size="sm" data-media-replace="" onClick={() => setReplacing(true)}>
+            <Upload className="size-4" aria-hidden />
+            {t('media.replace', 'Replace file')}
+          </Button>
+        ) : null}
+      </div>
+      {creates ? <p className="text-muted-foreground text-xs">{t('media.replaceAbout', 'Replace file uploads a new image and opens it. This one stays until you delete it.')}</p> : null}
+      <NewImageDialog open={replacing} onOpenChange={setReplacing} />
+    </div>
+  )
+}
+
+/**
+ * The New page, `/media/new`, which the list's New button opens: the upload
+ * dialog, open at once, and the page under it, which opens it again. Closing
+ * it goes back to the list.
+ */
+export function NewImage(_props: ComponentProps) {
+  const { t } = useLocale()
+  const { path, kayan } = useScreen()
+  const [open, setOpen] = useState(true)
+  const list = `${path}${kayan.media?.pages.list?.path ?? ''}`
+  return (
+    <AppShell
+      regions={{
+        header: <h1>{t('media.new', 'New image')}</h1>,
+        main: (
+          <div data-media-new="" className="grid justify-items-start gap-4">
+            <p className="text-muted-foreground">{t('media.newAbout', 'Choose an image and describe it. It is uploaded before it is saved.')}</p>
+            <Button type="button" onClick={() => setOpen(true)}>
+              <Upload className="size-4" aria-hidden />
+              {t('admin.upload.new', 'Upload new')}
+            </Button>
+            <NewImageDialog
+              open={open}
+              onOpenChange={(next) => {
+                setOpen(next)
+                if (!next) window.location.assign(list)
+              }}
+            />
+          </div>
+        ),
+      }}
+    />
+  )
+}

package/template/templates/features/media/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@asas/media",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*",
+    "mithaq-admin": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.3.0"
+  }
+}

package/template/templates/features/roles/index.ts

@@ -0,0 +1,4 @@
+import { memberRoles } from './member-roles/member-roles.ts'
+import { roles } from './roles/roles.ts'
+
+export const kayan = [roles, memberRoles] as const

package/template/templates/features/roles/member-roles/member-roles.ts

@@ -0,0 +1,207 @@
+import { sql } from 'mithaq/drizzle'
+import type { NodePgDatabase } from 'mithaq/drizzle/node-postgres'
+import { assignableRole, conflict, defaultFields, defaultOperations, denied, type Ctx, type WriteTools } from 'mithaq'
+import { defineKayan, backofficeUi, rows, organization } from '@asas/mithaq'
+import { backofficeList, backofficeRecord } from '@asas/mithaq/mithaq/pages.ts'
+import { tenantRoles } from '@asas/mithaq/roles/system-roles.ts'
+import { backofficeReads } from '@asas/mithaq/roles/tenant-access.ts'
+import { managesRoles, OWNER, OWNER_ROLE } from '@asas/mithaq/roles/grants.ts'
+
+const role = { field: 'role', cell: backofficeUi('role-cells.tsx#RoleName') } as const
+
+/**
+ * Nobody takes from themselves the role that lets them manage roles: their own
+ * `administrator`, or any role holding a key that manages roles. Another member
+ * holding the same keys removes it.
+ *
+ * A custom role's keys are read as the actor, through the role kayan's own
+ * access, so a role the actor may not read is refused rather than taken off
+ * unchecked. It guards a member's own row; two administrators removing each
+ * other at once are `managerRemains`' to refuse.
+ */
+const keepsOwnManager = async (ctx: Ctx, tools: WriteTools): Promise<Ctx> => {
+  const before = ctx.dataBefore
+  const me = (ctx.actor as { id?: unknown } | undefined)?.id
+  if (!before || me === undefined || before.user !== me) return ctx
+  const after = { ...before, ...(ctx.data as Record<string, unknown>) }
+  if (tools.kind === 'update' && after.user === before.user && after.role === before.role) return ctx
+  const role = String(before.role)
+  const roles = (tools.kayans as { roles: { find(input: object): Promise<{ docs: { permissions?: unknown }[] }> } }).roles
+  const keys = Object.hasOwn(tenantRoles, role)
+    ? tenantRoles[role as keyof typeof tenantRoles].permissions
+    : (await roles.find({ where: { name: { equals: role } } })).docs.flatMap((row) => (Array.isArray(row.permissions) ? (row.permissions as string[]) : []))
+  if (!managesRoles(keys)) return ctx
+  throw denied({
+    message: `Forbidden: role "${role}" is what lets this member manage roles, so it is not taken from themselves. Another member who may manage roles removes it.`,
+    key: 'error.forbidden.own_role',
+    params: { kayan: ctx.kayan.name, role },
+  })
+}
+
+/** The write's transaction, which is drizzle's here. */
+const txOf = (ctx: Ctx) => ctx.tx as NodePgDatabase
+
+/**
+ * How many assignments of one tenant name one role, counted inside the write's
+ * own transaction rather than read as the actor: a number leaves this function
+ * and no row does, so a role's author needs no `memberRoles` key to learn
+ * whether a name is still carried.
+ */
+export const assignedCount = async ({ ctx, tenantId, role }: { ctx: Ctx; tenantId: unknown; role: string }): Promise<number> => {
+  const [found] = (
+    await txOf(ctx).execute<{ total: number }>(sql`select count(*)::int as total from member_roles where organization_id = ${String(tenantId)} and role = ${role}`)
+  ).rows
+  return found?.total ?? 0
+}
+
+/**
+ * What a write changes about who manages roles: an assignment removed, or
+ * moved to another member or role, or a custom role's keys, which are `[]`
+ * when it is deleted.
+ */
+type Change = { assignment: Readonly<Record<string, unknown>>; becomes?: { user: unknown; role: unknown } } | { role: string; keys: readonly string[] }
+
+/**
+ * **Every tenant keeps a member who may manage roles**: one holding a role whose
+ * keys `managesRoles` answers for, or the organization's owner, who always holds
+ * `administrator`. A write that would leave none is refused 409
+ * `error.conflict.last_manager`. Removing the owner's own `administrator` row
+ * changes nothing the owner holds, so it is refused too, 403
+ * `error.forbidden.owner_role`.
+ *
+ * The check runs under `pg_advisory_xact_lock` on the tenant, held to the end of
+ * the write's transaction, and every guarded write takes the same lock first, so
+ * two administrators removing each other at once are serialized and the second
+ * reads the first's removal. `FOR UPDATE` on the manager assignments would not
+ * do: which assignments manage roles also depends on the roles table, and a role
+ * losing its keys touches no assignment row.
+ *
+ * Rows are read through the store rather than as the actor, because the answer
+ * is about every member of the tenant and the actor may read few of them;
+ * nothing read leaves this function but the refusal.
+ */
+export const managerRemains = async ({ ctx, tenantId, change }: { ctx: Ctx; tenantId: unknown; change: Change }): Promise<void> => {
+  const tx = txOf(ctx)
+  const tenant = String(tenantId)
+  await tx.execute(sql`select pg_advisory_xact_lock(hashtext('mithaq.managers'), hashtext(${tenant}))`)
+  const owners = (
+    await tx.execute<{ user: string }>(
+      sql`select user_id as "user" from member where organization_id = ${tenant} and ${OWNER} = any(string_to_array(role, ','))`,
+    )
+  ).rows.map((row) => row.user)
+  if ('assignment' in change) {
+    const { assignment, becomes } = change
+    if (assignment.role === OWNER_ROLE && owners.includes(String(assignment.user)) && (becomes?.role !== assignment.role || becomes.user !== assignment.user)) {
+      throw denied({
+        message: `Forbidden: the organization's owner always holds "${OWNER_ROLE}", so the row saying so is not taken from them.`,
+        key: 'error.forbidden.owner_role',
+        params: { kayan: ctx.kayan.name, role: OWNER_ROLE },
+      })
+    }
+  }
+  if (owners.length) return
+  const assigned = (await tx.execute<{ id: string; user: string; role: string }>(sql`select id, user_id as "user", role from member_roles where organization_id = ${tenant}`)).rows
+  const custom = new Map<string, readonly string[]>(
+    (await tx.execute<{ name: string; permissions: string[] }>(sql`select name, permissions from roles where organization_id = ${tenant}`)).rows.map((row) => [row.name, row.permissions] as const),
+  )
+  if ('keys' in change) custom.set(change.role, change.keys)
+  const keysOf = (role: string) => (Object.hasOwn(tenantRoles, role) ? tenantRoles[role as keyof typeof tenantRoles].permissions : (custom.get(role) ?? []))
+  const after = assigned.flatMap((row) => {
+    if (!('assignment' in change) || row.id !== change.assignment.id) return [row]
+    return change.becomes ? [{ ...row, role: String(change.becomes.role) }] : []
+  })
+  if (after.some((row) => managesRoles(keysOf(row.role)))) return
+  throw conflict({
+    message: `This write would leave the tenant with no member who may manage roles, so it is refused. Give another member such a role first.`,
+    key: 'error.conflict.last_manager',
+    params: { kayan: ctx.kayan.name },
+  })
+}
+
+/** `managerRemains` for an assignment's update or delete; an update that neither moves the row nor changes its role changes nothing. */
+const keepsAManager = async (ctx: Ctx, tools: WriteTools): Promise<Ctx> => {
+  const before = ctx.dataBefore
+  if (!before) return ctx
+  const after = tools.kind === 'update' ? { ...before, ...(ctx.data as Record<string, unknown>) } : undefined
+  if (after && after.user === before.user && after.role === before.role) return ctx
+  await managerRemains({ ctx, tenantId: before.organization, change: { assignment: before, ...(after && { becomes: { user: after.user, role: after.role } }) } })
+  return ctx
+}
+
+/**
+ * Who holds which of this project's roles, per tenant: one row per member per
+ * role. It exists so that Better Auth's own `member.role` never carries a
+ * business role name beside its governance one: a role name holding a comma would
+ * be accepted by `create-role` and could never be assigned again, because that
+ * column is comma-delimited.
+ *
+ * The access target reads it straight from the store while the actor is being
+ * made, filtered on this tenant and this member, so another tenant's row is
+ * never in what comes back.
+ */
+export const memberRoles = defineKayan({
+  name: 'memberRoles',
+  dbName: 'member_roles',
+  targets: {
+    // Every organization's rows on the backoffice, read-only, and each row's
+    // record. An assignment is looked for by its person, is titled by them, and
+    // reads its role by the role's label, never its slug.
+    backoffice: {
+      useAsTitle: 'user',
+      pages: {
+        ...backofficeList('/member-roles', { columns: ['user', role, 'organization'], filters: ['organization', 'user', 'role'], search: ['user.name', 'user.email'] }),
+        ...backofficeRecord({ path: '/member-roles/:id', main: [{ section: 'assignment', label: { en: 'Assignment', ar: 'الإسناد' }, fields: ['user', role] }] }),
+      },
+    },
+    // No dashboard page and so no nav entry: a member's roles are changed on the
+    // Members page's sheet, which writes these rows through the operations below,
+    // guards and all.
+    service: {
+      operations: {
+        ...defaultOperations,
+        // The gate in front of the store step: the runner has parsed by then, so
+        // the column is a string, and the write has not happened, so a refused
+        // assignment leaves no row. Without it a custom role holding
+        // `memberRoles.create` assigns itself `administrator`. It is handed the
+        // tenant roles alone, so a backoffice role such as `support` reads as an
+        // unknown custom role and is refused 400. `'roles'` is the kayan it reads
+        // the tenant's custom roles from.
+        create: { steps: ({ steps }) => [assignableRole(tenantRoles, 'roles'), steps.insert] },
+        update: { steps: ({ steps }) => [assignableRole(tenantRoles, 'roles'), keepsOwnManager, keepsAManager, steps.update] },
+        // Removing an assignment is measured the way handing it out is. Without it
+        // an actor delegated `memberRoles.delete` removes the tenant's only
+        // administrator row. The guard reads the row the store holds, because a
+        // delete names no column.
+        delete: { steps: ({ steps }) => [assignableRole(tenantRoles, 'roles'), keepsOwnManager, keepsAManager, steps.remove] },
+      },
+    },
+  },
+  // Its own rows, since the inherited table would close the instructor's
+  // delete here. Every backoffice role reads the assignments of every tenant in
+  // the backoffice app and changes none; in the tenant app `assignedRoles` omits
+  // the backoffice slugs.
+  access: rows({
+    '*': { create: true, read: true, update: true, delete: true },
+    ...backofficeReads,
+  }),
+  /** A member holds a role once per tenant. A second assignment answers 409 `error.conflict.unique`. */
+  indexes: [{ within: 'organization', unique: [['user', 'role']] }],
+  fields: {
+    ...defaultFields,
+    organization,
+    user: {
+      kind: 'relationship',
+      label: { ar: 'العضو', en: 'Member' },
+      relationTo: 'user',
+      // The assignment goes with the member: a deleted user holds no role, and
+      // `restrict`, which a required relationship takes by default, would leave a
+      // row nothing can reach standing in the way of the delete.
+      rules: { required: true, index: true, onDelete: 'cascade' },
+    },
+    role: {
+      kind: 'text',
+      label: { ar: 'الدور', en: 'Role' },
+      rules: { required: true, maxLength: 60, index: true },
+    },
+  },
+})

package/template/templates/features/roles/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@asas/roles",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./roles/ui/*": "./roles/ui/*"
+  },
+  "dependencies": {
+    "@asas/auth": "*",
+    "@asas/mithaq": "*",
+    "mithaq": "*",
+    "mithaq-admin": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.3.0"
+  }
+}

package/template/templates/features/roles/roles/roles.ts

@@ -0,0 +1,184 @@
+import { actorRoles, conflict, defaultFields, denied, folderOf, grantedPermissions, writableRoleName, defaultOperations, type Ctx, type WriteTools } from 'mithaq'
+import { user as users } from '@asas/auth'
+import { assignedCount, managerRemains, memberRoles } from '../member-roles/member-roles.ts'
+import { managesRoles } from '@asas/mithaq/roles/grants.ts'
+import { defineKayan, rows, organization } from '@asas/mithaq'
+import { appPage, backofficeList, backofficeRecord } from '@asas/mithaq/mithaq/pages.ts'
+import { systemRoles } from '@asas/mithaq/roles/system-roles.ts'
+import { backofficeReads } from '@asas/mithaq/roles/tenant-access.ts'
+
+const rolesUi = folderOf(new URL('./ui/', import.meta.url))
+
+/**
+ * A tenant's own roles, each with a flat list of the catalog keys it grants. The roles this project ships are code, `systemRoles`, and never a row here;
+ * a granter may not hand over a key it does not itself hold.
+ */
+/**
+ * A tenant's role never holds `screen.backoffice`, which only a backoffice role holds: a row naming it would be a tenant claiming the backoffice.
+ * It is refused before the granter check, so a root granter holding `'*'` is refused too.
+ */
+const BACKOFFICE_KEY = 'screen.backoffice'
+const tenantKeysOnly = (ctx: Ctx): Ctx => {
+  const written = (ctx.data as Record<string, unknown>).permissions
+  if (!Array.isArray(written) || !written.includes(BACKOFFICE_KEY)) return ctx
+  throw denied({
+    message: `Forbidden: a "${ctx.kayan.name}" row is a tenant's role, and "${BACKOFFICE_KEY}" is held only by a backoffice role.`,
+    key: 'error.forbidden.backoffice_key',
+    params: { kayan: ctx.kayan.name, permissions: [BACKOFFICE_KEY] },
+  })
+}
+
+const assignments = (tools: WriteTools, role: string) =>
+  tools.of(memberRoles).find({ where: { role: { equals: role } }, limit: 100 })
+
+/**
+ * A role a member holds is neither deleted nor renamed, and no role takes a name an assignment of its tenant already names: either would leave a `memberRoles` row naming a role that is gone, armed later by a role with that name. Both refuse 409.
+ * Holders are read as the actor, and an actor who may not read them is refused, because a write nobody could check does not go ahead. Assignments are counted through the store, so a role's author needs no `memberRoles` key.
+ */
+const unheld = async (ctx: Ctx, tools: WriteTools): Promise<Ctx> => {
+  const before = ctx.dataBefore
+  const name = before?.name
+  const renamed = (ctx.data as { name?: unknown }).name
+  const arriving = tools.kind === 'insert' || (tools.kind === 'update' && renamed !== name) ? renamed : undefined
+  // The runner fills the organization on a create, and it is the active one.
+  const tenantId = before?.organization ?? (ctx.data as { organization?: unknown }).organization
+  if (typeof arriving === 'string') {
+    const standing = await assignedCount({ ctx, tenantId, role: arriving })
+    if (standing) {
+      throw conflict({
+        message: `Role "${arriving}" is named by ${standing} assignment(s) of this tenant that outlived their role, so no role takes that name until they are removed.`,
+        key: 'error.conflict.role_assigned',
+        params: { kayan: ctx.kayan.name, role: arriving, count: standing },
+      })
+    }
+  }
+  if (typeof name !== 'string' || (tools.kind === 'update' && (renamed === undefined || renamed === name))) return ctx
+  const held = await assignments(tools, name)
+  if (!held.totalDocs) return ctx
+  const ids = held.docs.map((row) => String(row.user))
+  const named = await tools.of(users).find({ where: { id: { in: ids } }, limit: 100 }).catch(() => ({ docs: [] as { id?: unknown; name?: unknown }[] }))
+  const members = ids.map((id) => ({ id, name: String(named.docs.find((one) => one.id === id)?.name ?? id) }))
+  throw conflict({
+    message: `Role "${name}" is held by ${held.totalDocs} member(s), so it is not ${tools.kind === 'remove' ? 'deleted' : 'renamed'} until none holds it.`,
+    key: 'error.conflict.role_held',
+    params: { kayan: ctx.kayan.name, role: name, count: held.totalDocs, members },
+  })
+}
+
+const keysOf = (value: unknown): readonly string[] => (Array.isArray(value) ? (value as string[]) : [])
+
+/**
+ * Nobody edits a role they hold so it stops letting them manage roles. The actor's roles are the ones the access target resolved for this tenant,
+ * off the trusted snapshot; another member who may manage roles edits it.
+ */
+const keepsOwnRole = (ctx: Ctx): Ctx => {
+  const before = ctx.dataBefore
+  const keys = (ctx.data as { permissions?: unknown }).permissions
+  if (!before || keys === undefined || !managesRoles(keysOf(before.permissions)) || managesRoles(keysOf(keys))) return ctx
+  // The roles an assignment gives, not `assignedRoles`: the owner's added
+  // `administrator` is a fixed role, which no update reaches.
+  if (!actorRoles(ctx.actor)?.includes(String(before.name))) return ctx
+  throw denied({
+    message: `Forbidden: role "${String(before.name)}" is what lets this member manage roles, so they do not take its role-managing keys from it. Another member who may manage roles changes it.`,
+    key: 'error.forbidden.own_role',
+    params: { kayan: ctx.kayan.name, role: String(before.name) },
+  })
+}
+
+/** A role that lets its holders manage roles loses that only while another member still may, whether its keys change or it is deleted. */
+const keepsManagers = async (ctx: Ctx, tools: WriteTools): Promise<Ctx> => {
+  const before = ctx.dataBefore
+  if (!before || !managesRoles(keysOf(before.permissions))) return ctx
+  const keys = tools.kind === 'remove' ? [] : keysOf((ctx.data as { permissions?: unknown }).permissions ?? before.permissions)
+  if (managesRoles(keys)) return ctx
+  await managerRemains({ ctx, tenantId: before.organization, change: { role: String(before.name), keys } })
+  return ctx
+}
+
+const rolesAccess = rows({
+  '*': { create: true, read: true, update: true, delete: true },
+  /**
+   * Every backoffice role reads the role rows of every tenant, and writes none. A
+   * tenant that lost its administrator is repaired through `mithaq rbac assign`,
+   * never from the backoffice app.
+   */
+  ...backofficeReads,
+})
+
+export const roles = defineKayan({
+  name: 'roles',
+  targets: {
+    /** Every organization's rows on the backoffice, read-only. */
+    backoffice: {
+      useAsTitle: 'label',
+      pages: {
+        // A role by its label, never its slug, and its keys grouped as the
+        // dashboard draws a fixed role's.
+        ...backofficeList('/roles', { columns: ['label', 'organization'], filters: ['organization'], search: ['label'] }),
+        ...backofficeRecord({
+          path: '/roles/:id',
+          main: [{ section: 'role', label: { en: 'Role', ar: 'الدور' }, fields: ['label', { field: 'permissions', cell: rolesUi('roles.tsx#Permissions') }] }],
+        }),
+      },
+    },
+    service: {
+      operations: {
+        ...defaultOperations,
+        // The shipped lists with the guard in front of the store step: the runner
+        // has parsed by then, so the column is already a list of strings, and the
+        // write has not happened, so a refused grant leaves no row behind.
+        create: { steps: ({ steps }) => [tenantKeysOnly, grantedPermissions, writableRoleName(systemRoles), unheld, steps.insert] },
+        update: { steps: ({ steps }) => [tenantKeysOnly, grantedPermissions, writableRoleName(systemRoles), unheld, keepsOwnRole, keepsManagers, steps.update] },
+        delete: { steps: ({ steps }) => [grantedPermissions, unheld, keepsManagers, steps.remove] },
+      },
+    },
+    /**
+     * The fixed roles list first, from their code, each with a lock and its keys; a custom role opens its form, where its keys are picked as badges, and its delete names the members who still hold it.
+     */
+    dashboard: {
+      useAsTitle: 'label',
+      description: {
+        en: 'What each role in this organization may see and do.',
+        ar: 'ما يمكن لكل دور في هذه المؤسسة أن يراه ويفعله.',
+      },
+      pages: {
+        list: { path: '/roles', page: appPage([{ layout: 'table', main: [{ list: { columns: ['label', 'name', 'permissions'], limit: 100 }, component: rolesUi('roles.tsx#RolesTable') }] }]) },
+        create: { path: '/roles/new', page: appPage([{ layout: 'record', main: [{ form: ['name', 'label', 'permissions'], component: rolesUi('role-form.tsx#RoleForm') }] }]) },
+        edit: {
+          path: '/roles/:id',
+          page: appPage([
+            {
+              layout: 'record',
+              main: [{ form: ['name', 'label', 'permissions'], component: rolesUi('role-form.tsx#RoleForm') }],
+              danger: [{ button: 'delete', label: { en: 'Delete', ar: 'حذف' }, component: rolesUi('roles.tsx#DeleteRole') }],
+            },
+          ]),
+        },
+      },
+    },
+  },
+  access: rolesAccess,
+  fields: {
+    ...defaultFields,
+    organization,
+    // Unique within the organization: two rows of one name would each grant their keys, so
+    // deleting the one meant to revoke would leave the other granting.
+    name: {
+      kind: 'text',
+      label: { en: 'Name', ar: 'الاسم' },
+      // Trimmed, as the label below is, so neither is spaces alone.
+      rules: { required: true, unique: true, trim: true, maxLength: 60, index: true },
+    },
+    /** What a person reads a role by, everywhere; the name is the slug an assignment names. */
+    label: {
+      kind: 'text',
+      label: { en: 'Label', ar: 'التسمية' },
+      rules: { required: true, localized: true, trim: true, maxLength: 60 },
+    },
+    permissions: {
+      kind: 'textArray',
+      label: { en: 'Permissions', ar: 'الصلاحيات' },
+      rules: { required: true },
+    },
+  },
+})