create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/features/audit-log/audit-log/audit-log.ts

@@ -0,0 +1,284 @@
+import { actorPermissions, count, defaultFields, defaultJsonMaxBytes, denied, find, findOne, invalid, type Ctx, type Held } from 'mithaq'
+import { defineKayan, rows, organization } from '@asas/mithaq'
+import { backofficeClosed } from '@asas/mithaq/roles/tenant-access.ts'
+import { auditLogName, type Change } from '@asas/mithaq/mithaq/audit-sink.ts'
+
+/** The kayan whose `find` this actor holds, which are the kayan whose entries it reads. */
+const heldKayans = (held: Exclude<Held, true | undefined>) =>
+  [...held].filter((key) => key.endsWith('.find') && !key.includes('.fields.')).map((key) => key.slice(0, -'.find'.length))
+
+/**
+ * The read the log's rows are ANDed with, so it narrows and never widens: an
+ * entry of a kayan the actor may not list is no entry it reads. An actor
+ * nothing grades reads none, which is the closed direction.
+ */
+const readableKayans = ({ user }: { user: unknown }) => {
+  const held = actorPermissions(user)
+  if (held === true) return true
+  const kayans = held ? heldKayans(held) : []
+  return kayans.length ? { kayan: { in: kayans } } : false
+}
+
+/**
+ * Whether this actor reads one column of the kayan an entry names. The access
+ * target grades every column of this project by its key.
+ */
+const readsField = (held: Held, kayan: string, field: string) => held === true || held?.has(`${kayan}.fields.${field}`) === true
+
+/**
+ * Whether this actor reads the provider's people, by the key of their `find`.
+ * A command's operating-system user is the one thing in the log that names a
+ * person no row of the people does, so only such a reader sees or asks for it.
+ */
+const readsPeople = (held: Held) => held === true || held?.has('user.find') === true
+
+/**
+ * What the sink writes for a command: the command, then the operating-system
+ * user in parentheses. The command is the shortest part before ` (`, so a user
+ * holding a parenthesis is never left in it.
+ */
+const commandActor = /^(.+?) \(.+\)$/
+
+/**
+ * The step after the read: each entry keeps the changes of the columns the
+ * actor may read and drops the rest whole, so a column it may not read shows
+ * neither value nor that it changed. The server does it rather than the page,
+ * because the log is read over HTTP as well as drawn.
+ */
+const visibleChanges = (ctx: Ctx): Ctx => {
+  const held = actorPermissions(ctx.actor)
+  const trim = (entry: unknown) => {
+    const changes = (entry as { changes?: unknown } | null)?.changes
+    if (!changes || typeof changes !== 'object') return entry
+    const { kayan, actor } = entry as { kayan: string; actor?: unknown }
+    const kept = Object.fromEntries(Object.entries(changes as Record<string, Change>).filter(([field]) => readsField(held, kayan, field)))
+    // A command's actor is the command alone to a reader of no people, its operating-system user blanked.
+    const named = !readsPeople(held) && typeof actor === 'string' ? { actor: commandActor.exec(actor)?.[1] ?? actor } : {}
+    return { ...(entry as object), ...named, changes: kept }
+  }
+  const data: unknown = ctx.data
+  const page = data && typeof data === 'object' && Array.isArray((data as { docs?: unknown }).docs) ? (data as { docs: unknown[] }) : undefined
+  return { ...ctx, data: (page ? { ...page, docs: page.docs.map(trim) } : trim(data)) as Record<string, unknown> }
+}
+
+/**
+ * The columns the log is filtered and ordered by. The organization is core's
+ * own filter and `impersonatedBy` names staff.
+ */
+const queryable = new Set(['kayan', 'record', 'createdAt', 'operation', 'actor'])
+
+/**
+ * What the log is searched by besides those, never ordered by: `changes`, the
+ * whole of each change, or a path into it, `changes.<column>` and deeper. Each
+ * search takes any of the json kind's operators and reaches only the kayan whose
+ * columns it may tell of (`reachOf`), because a match in a column the reader
+ * holds no key for would say what that column held before `visibleChanges`
+ * trims the page.
+ */
+const searched = 'changes'
+
+/** The field a `where` key names: `changes.title.to` names `changes`. */
+const fieldOf = (key: string) => key.split('.')[0]!
+
+const namedIn = (where: unknown): string[] => {
+  if (!where || typeof where !== 'object') return []
+  return Object.entries(where).flatMap(([key, value]) =>
+    (key === 'and' || key === 'or') && Array.isArray(value) ? value.flatMap(namedIn) : [key])
+}
+
+/** Every column key the catalog holds, by the kayan it belongs to. */
+const columnsOf = (catalog: readonly string[]) => {
+  const columns = new Map<string, string[]>()
+  for (const key of catalog) {
+    const at = key.indexOf('.fields.')
+    if (at > 0) columns.set(key.slice(0, at), [...(columns.get(key.slice(0, at)) ?? []), key])
+  }
+  return columns
+}
+
+// ponytail: the reach here and `visibleChanges` grade by keys alone. A tenant role that a row
+// table narrows further, by a `fields` list or a row filter on its read, would be told of columns
+// and rows its own reads hide; grade each entry through the kayan's own field access and read
+// `where` before a project adds one.
+/**
+ * The kayan one search of a change reaches for this actor, or `true` for every
+ * one. The whole change reaches a kayan whose every column the actor reads, since
+ * it matches any of them; a path into one column, `changes.<column>`, a kayan
+ * whose column of that name it reads, since it matches inside that column alone.
+ */
+const reachOf = ({ held, catalog }: { held: Held; catalog: readonly string[] }) => (key: string): true | string[] => {
+  if (held === true) return true
+  const column = key.split('.')[1]
+  return [...columnsOf(catalog)]
+    .filter(([kayan, keys]) => held?.has(`${kayan}.find`) && (column === undefined ? keys.every((one) => held.has(one)) : held.has(`${kayan}.fields.${column}`)))
+    .map(([kayan]) => kayan)
+}
+
+/**
+ * The `where` with each search of a change ANDed, where it stands, with the kayan
+ * it reaches, so an `or` around it still means what it said, and a negation, a
+ * `not_equals` or an `exists: false`, still answers no entry past its reach.
+ */
+const narrowed = (where: unknown, reach: (key: string) => true | string[]): unknown => {
+  if (!where || typeof where !== 'object') return where
+  const parts = Object.entries(where).map(([key, value]) => {
+    if ((key === 'and' || key === 'or') && Array.isArray(value)) return { [key]: value.map((one) => narrowed(one, reach)) }
+    if (fieldOf(key) !== searched) return { [key]: value }
+    const kayans = reach(key)
+    return kayans === true ? { [key]: value } : { and: [{ [key]: value }, { kayan: { in: kayans } }] }
+  })
+  return parts.length === 1 ? parts[0] : { and: parts }
+}
+
+/**
+ * The step before the read: a `where` naming any column but those above, or a
+ * `sort` by any but the queryable ones, is refused 400 before the store is
+ * asked, on every read the log declares, and each search of a change is narrowed
+ * to the kayan it reaches. The runner's own checks still run after it on what it
+ * lets through.
+ */
+const queriedByQueryable = (ctx: Ctx, tools: { catalog: readonly string[] }): Ctx => {
+  // The runner names the organization a read is scoped to only where the read is not widened.
+  // `reachOf` and `visibleChanges` grade by the active organization's keys, so a read across every
+  // membership (`tenant: 'mine'`) would grade another organization's entries by this one's: it is
+  // refused before anything else of it is judged.
+  if (ctx.tenant === undefined) {
+    throw denied({ message: 'Kayan "auditLog" is read in the active organization alone.', key: 'error.forbidden.read', params: {} })
+  }
+  const { where, sort } = ctx.data as { where?: unknown; sort?: unknown }
+  const field = namedIn(where).find((name) => !queryable.has(name) && fieldOf(name) !== searched)
+  if (field !== undefined) {
+    throw invalid({ message: `Kayan "auditLog" is filtered by ${[...queryable, searched].join(', ')} alone, and not by "${field}".`, key: 'error.invalid.where', params: { kayan: 'auditLog', field } })
+  }
+  const held = actorPermissions(ctx.actor)
+  // A reader of no people names an actor in no filter and no sort: a pattern, a range, an order or
+  // even an equality over the string would let it confirm a guessed operating-system user of a
+  // command's actor.
+  if (!readsPeople(held) && (namedIn(where).includes('actor') || (typeof sort === 'string' && sort.replace(/^-/, '') === 'actor'))) {
+    throw invalid({ message: 'Kayan "auditLog" is neither filtered nor sorted by "actor" for a reader of no people.', key: 'error.invalid.where', params: { kayan: 'auditLog', field: 'actor' } })
+  }
+  if (sort !== undefined && !(typeof sort === 'string' && queryable.has(sort.replace(/^-/, '')))) {
+    throw invalid({ message: `Kayan "auditLog" is sorted by ${[...queryable].join(', ')} alone.`, key: 'error.invalid.sort_field', params: { kayan: 'auditLog', field: String(sort) } })
+  }
+  return where === undefined ? ctx : { ...ctx, data: { ...ctx.data, where: narrowed(where, reachOf({ held, catalog: tools.catalog })) } }
+}
+
+/**
+ * The audit log's rows: an organization reads its own entries, and nothing writes
+ * one through the log, a caller of any role included, since the service
+ * target's sink writes each entry through the store inside the write it
+ * records. Every backoffice role is closed: the backoffice lists no entry, and a
+ * staff member's own impersonated writes are the entries it would read.
+ */
+const auditLogAccess = rows({
+  '*': { create: false, read: true, update: false, delete: false },
+  ...backofficeClosed,
+})
+
+/**
+ * The audit log: one row per row a write changed, written by the service
+ * target's audit sink inside that write's own transaction and by nothing else.
+ * It declares no operation that writes, so no caller creates, edits or deletes
+ * an entry, and each of its rows answers `false` for every write besides.
+ *
+ * It is its organization's own. A record's last entries are read in its edit
+ * page's side column, all of them in its Activity tab, and the organization's on
+ * the dashboard's Activity page, a page of the screen's own rather than of this
+ * kayan, which draws none. The backoffice lists none of it and reads none of
+ * it: staff's own actions are its staff history, `backofficeLog`.
+ */
+export const auditLog = defineKayan({
+  name: auditLogName,
+  dbName: 'audit_log',
+  messages: {
+    singular: { en: 'Audit entry', ar: 'سجل تدقيق' },
+    plural: { en: 'Audit log', ar: 'سجل التدقيق' },
+    // What the activity panel draws beside the field labels.
+    activity: { en: 'Activity', ar: 'النشاط' },
+    loading: { en: 'Loading activity…', ar: 'جارٍ تحميل النشاط…' },
+    empty: { en: 'Nothing has changed here yet.', ar: 'لم يتغير شيء هنا بعد.' },
+    failed: { en: 'The activity could not be read.', ar: 'تعذرت قراءة النشاط.' },
+    more: { en: 'Show older', ar: 'عرض الأقدم' },
+    system: { en: 'The system', ar: 'النظام' },
+    event: { en: '{action} by {actor}', ar: '{action} بواسطة {actor}' },
+    // Staff writing as a member: the real person first, as the member they wrote as.
+    impersonated: { en: '{staff} as {member}', ar: '{staff} بصفة {member}' },
+    // One per operation a tenant kayan writes through, which is every entry the sink records.
+    action: {
+      create: { en: 'Created', ar: 'أُنشئ' },
+      update: { en: 'Updated', ar: 'حُدِّث' },
+      delete: { en: 'Deleted', ar: 'حُذف' },
+      updateMany: { en: 'Updated', ar: 'حُدِّث' },
+      deleteMany: { en: 'Deleted', ar: 'حُذف' },
+      restoreVersion: { en: 'Restored a version', ar: 'استُعيد إصدار' },
+      archive: { en: 'Archived', ar: 'أُرشف' },
+      archiveMany: { en: 'Archived', ar: 'أُرشف' },
+      unarchive: { en: 'Unarchived', ar: 'أُلغيت أرشفته' },
+      unpublish: { en: 'Unpublished', ar: 'أُلغي نشره' },
+      // An update that published a draft, which the sink names apart from a plain update.
+      publish: { en: 'Published', ar: 'نُشر' },
+    },
+    someone: { en: 'Someone', ar: 'شخص ما' },
+    // A command line write, named for a reader of the people: the command and
+    // the operating-system user who ran it.
+    command: { en: 'the command {command} ({user})', ar: 'الأمر {command} ({user})' },
+    // The viewer's own entry, which needs no read of the people to name. Its
+    // sentence is its own, since Arabic joins the person to "by" in one word,
+    // "بواسطتك", and not as "بواسطة أنت".
+    you: { en: 'You', ar: 'أنت' },
+    eventYou: { en: '{action} by You', ar: '{action} بواسطتك' },
+    none: { en: 'No field you may read changed.', ar: 'لم يتغير حقل يمكنك قراءته.' },
+    // Beside a change the sink cut to the start of its JSON, which a large json value is.
+    truncated: { en: 'Too long to keep whole; its start is shown.', ar: 'أطول من أن يُحفظ كاملا؛ تظهر بدايته.' },
+    // The panel's link to the rest of a record's entries, and the Activity page and tab.
+    all: { en: 'All activity', ar: 'كل النشاط' },
+    about: { en: 'Every change in this organization, newest first.', ar: 'كل تغيير في هذه المؤسسة، الأحدث أولا.' },
+    filters: { en: 'Filter the activity', ar: 'تصفية النشاط' },
+    // What the search box names as what it searches, in the sentence "Search changed values".
+    searchChanges: { en: 'changed values', ar: 'القيم المتغيرة' },
+    person: { en: 'Person', ar: 'الشخص' },
+    type: { en: 'Record type', ar: 'نوع السجل' },
+    field: { en: 'Field', ar: 'الحقل' },
+    actionFilter: { en: 'Action', ar: 'الإجراء' },
+    from: { en: 'From', ar: 'من' },
+    to: { en: 'To', ar: 'إلى' },
+    any: { en: 'Any', ar: 'الكل' },
+    filter: {
+      created: { en: 'Created', ar: 'أُنشئ' },
+      updated: { en: 'Updated', ar: 'حُدِّث' },
+      deleted: { en: 'Deleted', ar: 'حُذف' },
+      published: { en: 'Published', ar: 'نُشر' },
+      restored: { en: 'Restored', ar: 'استُعيد' },
+    },
+    clear: { en: 'Clear filters', ar: 'مسح عوامل التصفية' },
+    nothing: { en: 'No activity matches these filters.', ar: 'لا نشاط يطابق عوامل التصفية هذه.' },
+    oneRecord: { en: 'One record\'s activity.', ar: 'نشاط سجل واحد.' },
+    found: { en: 'Entries found: {count}', ar: 'السجلات المطابقة: {count}' },
+    searchLimited: { en: 'The search covers the records whose every field you may read.', ar: 'يشمل البحث السجلات التي يمكنك قراءة كل حقولها.' },
+  },
+  access: { ...auditLogAccess, read: readableKayans },
+  targets: {
+    dashboard: {},
+    service: {
+      operations: {
+        find: { steps: [queriedByQueryable, find, visibleChanges] },
+        findByID: { steps: [queriedByQueryable, findOne, visibleChanges] },
+        count: { steps: [queriedByQueryable, count] },
+      },
+    },
+  },
+  fields: {
+    id: defaultFields.id,
+    createdAt: defaultFields.createdAt,
+    organization,
+    kayan: { kind: 'text', label: { en: 'Kayan', ar: 'الكيان' }, rules: { required: true, maxLength: 60 } },
+    record: { kind: 'text', label: { en: 'Record', ar: 'السجل' }, rules: { required: true, index: true } },
+    operation: { kind: 'text', label: { en: 'Operation', ar: 'العملية' }, rules: { required: true, maxLength: 60 } },
+    actor: { kind: 'text', label: { en: 'Actor', ar: 'المنفذ' } },
+    impersonatedBy: { kind: 'text', label: { en: 'Impersonated by', ar: 'انتحل الصفة' } },
+    // Each changed column by name, so a search finds the change of one column by
+    // the path `changes.<column>`, which `queriedByQueryable` grades by that
+    // column's key. Never an order, as no json field is.
+    changes: { kind: 'json', label: { en: 'Changes', ar: 'التغييرات' }, maxBytes: defaultJsonMaxBytes, rules: { required: true } },
+  },
+})

package/template/templates/features/audit-log/backoffice-log/backoffice-log.ts

@@ -0,0 +1,67 @@
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan, rows } from '@asas/mithaq'
+import { backofficeList } from '@asas/mithaq/mithaq/pages.ts'
+import { backofficeReads } from '@asas/mithaq/roles/tenant-access.ts'
+
+/** Who did what to whom on the backoffice, as `action` names it. */
+const actions = [
+  { value: 'impersonate', label: { en: 'Started impersonating', ar: 'بدأ انتحال الصفة' } },
+  { value: 'stopImpersonating', label: { en: 'Stopped impersonating', ar: 'أنهى انتحال الصفة' } },
+  { value: 'setRole', label: { en: 'Set the backoffice role', ar: 'عيّن دور الإدارة الخلفية' } },
+  { value: 'ban', label: { en: 'Banned', ar: 'حظر' } },
+  { value: 'unban', label: { en: 'Lifted the ban', ar: 'رفع الحظر' } },
+] as const
+
+const text = (label: { en: string; ar: string }) => ({ kind: 'text', label }) as const
+
+/**
+ * The staff history: one row per impersonation started or stopped, backoffice
+ * role set and ban set or lifted, written by the auth setup's backoffice hook
+ * once the provider's route succeeded, and by nothing else. It belongs to no
+ * organization, since staff act above every tenant, and it declares no
+ * operation that writes, so no caller makes, edits or removes a row.
+ *
+ * Only a backoffice role reads it, in the backoffice app alone, and only one
+ * holding its keys: the row table names no `'*'` row, so a tenant's
+ * administrator, who holds every key of the project, takes no row of it and is
+ * refused. The tenant app's screens list none of it.
+ *
+ * Each person is kept by id and by the address they had then, so the history
+ * still says who once a person is renamed or removed.
+ */
+export const backofficeLog = defineKayan({
+  name: 'backofficeLog',
+  dbName: 'backoffice_log',
+  messages: {
+    singular: { en: 'Staff action', ar: 'إجراء طاقم' },
+    plural: { en: 'Staff history', ar: 'سجل الطاقم' },
+  },
+  access: rows({ ...backofficeReads }),
+  targets: {
+    service: {
+      operations: { find: defaultOperations.find, findByID: defaultOperations.findByID, count: defaultOperations.count },
+    },
+    backoffice: {
+      pages: {
+        ...backofficeList('/history', {
+          columns: ['createdAt', 'action', 'actorEmail', 'targetEmail', 'previousRole', 'role', 'banReason'],
+          filters: ['action', 'actorEmail', 'targetEmail', 'createdAt'],
+          search: ['actorEmail', 'targetEmail'],
+          sort: '-createdAt',
+        }),
+      },
+    },
+  },
+  fields: {
+    id: defaultFields.id,
+    createdAt: defaultFields.createdAt,
+    action: { kind: 'text', label: { en: 'Action', ar: 'الإجراء' }, options: actions, rules: { required: true } },
+    actor: text({ en: 'Staff member', ar: 'عضو الطاقم' }),
+    actorEmail: text({ en: 'Staff member\'s email', ar: 'بريد عضو الطاقم' }),
+    target: text({ en: 'Person', ar: 'الشخص' }),
+    targetEmail: text({ en: 'Person\'s email', ar: 'بريد الشخص' }),
+    previousRole: text({ en: 'Role before', ar: 'الدور السابق' }),
+    role: text({ en: 'Role after', ar: 'الدور الجديد' }),
+    banReason: text({ en: 'Ban reason', ar: 'سبب الحظر' }),
+  },
+})

package/template/templates/features/audit-log/index.ts

@@ -0,0 +1,4 @@
+import { auditLog } from './audit-log/audit-log.ts'
+import { backofficeLog } from './backoffice-log/backoffice-log.ts'
+
+export const kayan = [auditLog, backofficeLog] as const

package/template/templates/features/audit-log/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@asas/audit-log",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*"
+  }
+}

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

@@ -0,0 +1,11 @@
+import { localUsers } from './local-users/local-users.ts'
+// Written by `mithaq generate auth`: one key per plugin the vocabulary names,
+// and `core` for the four Better Auth ships without one. Spreading the keys is
+// what keeps this list from naming eight files, and a project that drops the
+// organization plugin drops one spread.
+import { betterAuth } from './user/index.ts'
+
+// The account other features point at, and the asas names its administrator by.
+export { user } from './user/user.ts'
+
+export const kayan = [...betterAuth.core, ...betterAuth.organization, localUsers] as const

package/template/templates/features/auth/local-users/local-users.ts

@@ -0,0 +1,143 @@
+import {
+  defaultFields,
+  defaultLockTime,
+  defaultMaxLoginAttempts,
+  defaultTokenExpiration,
+  local,
+  localAuthFields,
+  localAuthOperations,
+  defaultOperations,
+  type Ctx,
+} from 'mithaq'
+import { defineKayan, requestContext } from '@asas/mithaq'
+import { appPage, backofficeList } from '@asas/mithaq/mithaq/pages.ts'
+import { superAdmin } from '@asas/mithaq/roles/tenant-access.ts'
+
+/**
+ * The trusted-header names this deployment's own proxy overwrites with the real client address, read
+ * from the same `TRUSTED_IP_HEADER` variable Better Auth's `advanced.ipAddress.ipAddressHeaders` is
+ * fed from, so both limiters key on the same address. Unset, it falls back to `x-forwarded-for`.
+ */
+export const ip = (request: Request): string | null => {
+  const headers = process.env.TRUSTED_IP_HEADER?.split(',').map((header) => header.trim()).filter(Boolean) ?? [
+    'x-forwarded-for',
+  ]
+  for (const header of headers) {
+    const value = request.headers.get(header)?.split(',').at(-1)?.trim()
+    if (value) return value
+  }
+  return null
+}
+
+/**
+ * The secret local auth signs its tokens with, 32 characters at least, from the environment and
+ * never from this file: a secret written here is one anyone reading the repository forges a token
+ * with. Unset or empty, local auth is off as a whole: every POST to `/api/auth/local` answers
+ * `withoutSecret` below with a 503, and the public sign-up with a 403. The kayan keeps its provider,
+ * fields and operations, so the build and every file generated from it are the same in every
+ * environment.
+ */
+const secret = process.env.LOCAL_AUTH_SECRET || undefined
+
+const markVerified = (ctx: Ctx): Ctx => ({ ...ctx, data: { ...ctx.data, _verified: true } })
+
+/**
+ * The kayan the local auth provider writes. It spreads the shipped `localAuthFields` and
+ * `localAuthOperations`, so every column and step it has is written here, and the build refuses a
+ * protected column left readable.
+ */
+export const localUsers = defineKayan({
+  name: 'localUsers',
+  dbName: 'local_users',
+  messages: {
+    singular: { en: 'Local account', ar: 'حساب محلي' },
+    plural: { en: 'Local accounts', ar: 'الحسابات المحلية' },
+  },
+  // `context` is what first registration hands its steps.
+  //
+  // `ip` reads the last entry of whichever header `TRUSTED_IP_HEADER` names, the one the trusted proxy
+  // in front of it appended, because no host this template is served by hands the socket address to
+  // the `Request`. That is only safe behind exactly one such proxy: without one any caller writes the
+  // header, and behind more than one the last entry is the nearest proxy's own address, so every user
+  // would share one count; there, take the entry at the depth of the trusted proxies. A project served
+  // bare passes its server's own address instead, such as Bun's `server.requestIP(request)`. No header
+  // answers null, which leaves the request uncounted.
+  // No `email` is passed, so no mail is sent: a super admin verifies each sign-up in the backoffice app.
+  auth: local({
+    secret,
+    withoutSecret: 'Local sign-in is off on this server: LOCAL_AUTH_SECRET is not set. Set it to a secret of 32 characters at least and restart the server.',
+    context: requestContext,
+    ip,
+    tokenExpiration: defaultTokenExpiration,
+    maxLoginAttempts: defaultMaxLoginAttempts,
+    lockTime: defaultLockTime,
+  }),
+  targets: {
+    service: {
+      operations: {
+        ...defaultOperations,
+        ...localAuthOperations,
+        // The provider's own update with one step before it that writes `_verified: true` over whatever
+        // the call sent, so it can only verify; the access below judges it as an update with that one key
+        // as its data.
+        verify: { ...localAuthOperations.update, steps: [markVerified, ...localAuthOperations.update.steps] },
+      },
+    },
+    /**
+     * Where a super admin verifies a sign-up: the accounts by email, verified state and the date each
+     * was made, and an edit page whose form is the verified toggle alone. Its fields are written here,
+     * never read off `/api/access`, which reports `update` for `email` because the kayan's own `update`
+     * asks the data and the report has none; the access above still refuses any write but `_verified`.
+     * The form sends only what changed, so an unchanged toggle writes nothing and leaves `updatedAt`
+     * alone. The protected columns are named by no page, so no list offers one as a column or a filter.
+     */
+    backoffice: {
+      useAsTitle: 'email',
+      pages: {
+        ...backofficeList('/local-users', {
+          columns: ['email', '_verified', 'createdAt'],
+          filters: ['_verified'],
+          search: ['email'],
+          row: [{
+            button: 'verify',
+            when: { or: [{ 'record._verified': { exists: false } }, { 'record._verified': { equals: false } }] },
+            label: { en: 'Verify', ar: 'توثيق' },
+            confirm: {
+              title: { en: 'Verify this account?', ar: 'توثيق هذا الحساب؟' },
+              body: { en: 'Its owner can sign in from now on.', ar: 'يستطيع صاحبه تسجيل الدخول من الآن.' },
+            },
+          }],
+        }),
+        // Read-only above the toggle: a read-only leaf is drawn and never sent, so a save still writes
+        // `_verified` alone.
+        edit: {
+          path: '/local-users/:id',
+          page: appPage([{ layout: 'record', main: [{ form: [{ section: 'verification', label: { en: 'Verification', ar: 'التحقق' }, fields: [
+            { field: 'email', readOnly: true },
+            { field: 'createdAt', readOnly: true },
+            '_verified',
+          ] }] }] }]),
+        },
+      },
+    },
+  },
+  // Public sign-up stays open. A super admin, in the backoffice app alone, verifies an account by writing
+  // `_verified: true`, which the field's own write admits from the administrator and nobody else. The
+  // super admin writes `_verified` and nothing else: a password or an email it set would be an account
+  // it could then log in as, and no audit entry records a write to a kayan with no tenant. An
+  // `updateMany` is asked this again for each row it writes, with that row's values. Everyone else, a
+  // local user on its own row included, reads and writes none.
+  access: {
+    create: () => true,
+    read: superAdmin,
+    update: ({ user, data }) => superAdmin({ user }) && Object.keys(data ?? {}).every((key) => key === '_verified'),
+    delete: () => false,
+  },
+  // A label leaves the shipped access in place, which the build compares by identity.
+  fields: {
+    ...defaultFields,
+    ...localAuthFields,
+    email: { ...localAuthFields.email, label: { en: 'Email', ar: 'البريد الإلكتروني' } },
+    _verified: { ...localAuthFields._verified, label: { en: 'Verified', ar: 'موثق' } },
+  },
+})

package/template/templates/features/auth/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@asas/auth",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "dependencies": {
+    "@asas/mithaq": "*",
+    "mithaq": "*"
+  }
+}

package/template/templates/features/auth/user/account.access.ts

@@ -0,0 +1,8 @@
+// This project's access for the generated `account` kayan, which `mithaq generate
+// auth` imports into `./account.ts` because this file sits beside it.
+//
+// Better Auth alone writes and reads this table, through its own adapter, so
+// every managed operation on it is refused to every actor. Written out rather
+// than left to the administrator's default, which a super admin passes in the
+// backoffice app.
+export { providerOnly as access } from '@asas/mithaq/roles/tenant-access.ts'

package/template/templates/features/auth/user/account.ts

@@ -0,0 +1,31 @@
+// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.
+// This kayan's access and what each screen draws of it are the project's:
+// `account.access.ts` exporting `access` and `account.screens.ts` exporting
+// `screens`, beside this file, are imported here on the next run. A kayan
+// built under this one's name elsewhere is refused by every relationship to it.
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan } from '@asas/mithaq'
+import { user } from './user.ts'
+import { access } from './account.access.ts'
+
+export const account = defineKayan({
+  name: 'account',
+  targets: { service: { operations: defaultOperations } },
+  access,
+  fields: {
+    ...defaultFields,
+    id: { kind: 'text' },
+    accountId: { kind: 'text', rules: { required: true } },
+    providerId: { kind: 'text', rules: { required: true } },
+    userId: { kind: 'relationship', relationTo: () => user, dbName: 'user_id', rules: { required: true, index: true, onDelete: 'cascade' } },
+    accessToken: { kind: 'text' },
+    refreshToken: { kind: 'text' },
+    idToken: { kind: 'text' },
+    accessTokenExpiresAt: { kind: 'datetime' },
+    refreshTokenExpiresAt: { kind: 'datetime' },
+    scope: { kind: 'text' },
+    password: { kind: 'text' },
+    createdAt: { kind: 'datetime', rules: { required: true } },
+    updatedAt: { kind: 'datetime', rules: { required: true, nowOnUpdate: true, providedBy: { update: 'application' } } },
+  },
+})

package/template/templates/features/auth/user/index.ts

@@ -0,0 +1,18 @@
+// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.
+// One key per plugin that brought tables of its own, and `core` for the tables
+// Better Auth ships without one, so a project spreads these lists into
+// `buildAsas` instead of naming every file. A plugin that leaves takes its key
+// with it, and `mithaq generate auth --check` reports the drift.
+import { account } from './account.ts'
+import { invitation } from './invitation.ts'
+import { member } from './member.ts'
+import { organization } from './organization.ts'
+import { organizationRole } from './organizationRole.ts'
+import { session } from './session.ts'
+import { user } from './user.ts'
+import { verification } from './verification.ts'
+
+export const betterAuth = {
+  core: [user, session, account, verification],
+  organization: [organization, organizationRole, member, invitation],
+} as const

package/template/templates/features/auth/user/invitation.access.ts

@@ -0,0 +1,4 @@
+// Better Auth alone writes and reads this table, through its own adapter, so every managed
+// operation on it is refused to every actor. Written out rather than left to the administrator's
+// default, which a super admin passes.
+export { providerOnly as access } from '@asas/mithaq/roles/tenant-access.ts'

package/template/templates/features/auth/user/invitation.ts

@@ -0,0 +1,27 @@
+// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.
+// This kayan's access and what each screen draws of it are the project's:
+// `invitation.access.ts` exporting `access` and `invitation.screens.ts` exporting
+// `screens`, beside this file, are imported here on the next run. A kayan
+// built under this one's name elsewhere is refused by every relationship to it.
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan } from '@asas/mithaq'
+import { organization } from './organization.ts'
+import { user } from './user.ts'
+import { access } from './invitation.access.ts'
+
+export const invitation = defineKayan({
+  name: 'invitation',
+  targets: { service: { operations: defaultOperations } },
+  access,
+  fields: {
+    ...defaultFields,
+    id: { kind: 'text' },
+    organizationId: { kind: 'relationship', relationTo: () => organization, dbName: 'organization_id', rules: { required: true, index: true, onDelete: 'cascade' } },
+    email: { kind: 'text', rules: { required: true, index: true } },
+    role: { kind: 'text' },
+    status: { kind: 'text', rules: { required: true } },
+    expiresAt: { kind: 'datetime', rules: { required: true } },
+    createdAt: { kind: 'datetime', rules: { required: true } },
+    inviterId: { kind: 'relationship', relationTo: () => user, dbName: 'inviter_id', rules: { required: true, onDelete: 'cascade' } },
+  },
+})

package/template/templates/features/auth/user/member.access.ts

@@ -0,0 +1,10 @@
+// This project's access for the generated `member` kayan, which `mithaq
+// generate auth` imports into `./member.ts` because this file sits beside it. A
+// backoffice role reads every organization's members in the backoffice app, by the
+// keys it holds, and no one writes through it. There is no `'*'` row, so a
+// tenant's actor takes no row here and reads nothing: a tenant lists its
+// members through the provider's own `list-members`.
+import { rows } from '@asas/mithaq'
+import { backofficeReads } from '@asas/mithaq/roles/tenant-access.ts'
+
+export const access = rows(backofficeReads)