create-mithaq 0.0.0-stage → 0.2.0

package/template/templates/mithaq/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-maia",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "",
+    "baseColor": "stone",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "hugeicons",
+  "rtl": true,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/template/templates/mithaq/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@asas/mithaq",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/mithaq.ts",
+    "./auth": "./src/mithaq/auth/index.ts",
+    "./auth/backoffice-roles": "./src/mithaq/auth/backoffice-roles.ts",
+    "./auth/organizations": "./src/mithaq/auth/organizations.ts",
+    "./*": "./src/*"
+  },
+  "dependencies": {
+    "@better-auth/core": "1.7.4",
+    "@lexical/extension": "0.52.0",
+    "@lexical/link": "0.52.0",
+    "@lexical/list": "0.52.0",
+    "@lexical/rich-text": "0.52.0",
+    "aws4fetch": "1.0.20",
+    "better-auth": "1.7.4",
+    "file-type": "22.0.1",
+    "image-dimensions": "2.5.1",
+    "lexical": "0.52.0",
+    "mithaq": "*",
+    "mithaq-admin": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "lucide-react": "^1.16.0",
+    "react": "^19.3.0",
+    "zod": "^4.6.5"
+  }
+}

package/template/templates/mithaq/src/mail/index.ts

@@ -0,0 +1,32 @@
+// Which mailer this project sends with. `mailers.ts` beside this file is copied from the
+// `mithaq-mail` registry item and owned by the project; a project on another service writes its
+// adapter there and names it here. The auth setup sends the password reset, the invitation and the
+// email verification through it, and refuses an open sign-up in production while none is configured.
+import { defaultResendBaseURL, resendMailer, type Mailer } from './mailers.ts'
+
+export { logMailer, type Mail, type Mailer } from './mailers.ts'
+
+/**
+ * Resend when both `RESEND_API_KEY` and `MAIL_FROM` are set, none when neither is. Half the settings
+ * is refused, so a typo never leaves a deploy sending nothing while it seems configured.
+ * `RESEND_BASE_URL`, Resend's own SDK variable, points it at another address that speaks its API.
+ */
+export const mailerFromEnv = (env: Record<string, string | undefined>): Mailer | undefined => {
+  const { RESEND_API_KEY: apiKey, MAIL_FROM: from } = env
+  if (!apiKey && !from) return undefined
+  if (!apiKey) throw new Error('MAIL_FROM is set and RESEND_API_KEY is not. Set both, or neither.')
+  if (!from) throw new Error('RESEND_API_KEY is set and MAIL_FROM is not: set MAIL_FROM to an address at a domain your Resend account verified.')
+  const baseURL = env.RESEND_BASE_URL || defaultResendBaseURL
+  // The key and every letter cross to it, so in the clear only to this machine, such as a test's catcher.
+  const at = URL.canParse(baseURL) ? new URL(baseURL) : undefined
+  if (!at || (at.protocol !== 'https:' && !(at.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(at.hostname)))) {
+    throw new Error(`RESEND_BASE_URL is ${JSON.stringify(baseURL)}: set an https address, or http on this machine.`)
+  }
+  return resendMailer({ apiKey, from, baseURL })
+}
+
+/**
+ * The mailer this deploy configured, or none; the auth setup logs mail in development without one.
+ * The auth setup asks it as it loads, so every load reads the environment it is started with.
+ */
+export const configuredMailer = (): Mailer | undefined => mailerFromEnv(process.env)

package/template/templates/mithaq/src/mail/mailers.ts

@@ -0,0 +1,36 @@
+/** One message, written twice: plain text for every client, HTML for those that draw it. */
+export type Mail = { to: string; subject: string; text: string; html: string }
+
+/** What sends this project's mail: one function, so an adapter for another service is a few lines. */
+export type Mailer = { send(mail: Mail): Promise<void> }
+
+/**
+ * Development only: the message goes to the server's log, links and all, and nothing leaves the
+ * machine. Never use it in production, where the log would hold every reset and sign-in link.
+ */
+export const logMailer: Mailer = {
+  send: async ({ to, subject, text }) => {
+    // The log reads as an inbox, so nobody waits for a message that never left.
+    console.log(`[asas mail] Development: emails print here instead of being sent.\nTo ${to}: ${subject}\n${text}`)
+  },
+}
+
+/** Where Resend's API answers, as its own SDK names it. */
+export const defaultResendBaseURL = 'https://api.resend.com'
+
+/**
+ * Resend's HTTP API over `fetch`, so no SDK is installed. `from` is an address at a domain the Resend
+ * account verified; `baseURL` is another address that speaks Resend's API, such as a test's catcher.
+ * A refusal throws with the status alone: the address and the body stay out of the log.
+ */
+export const resendMailer = ({ apiKey, from, baseURL }: { apiKey: string; from: string; baseURL: string }): Mailer => ({
+  send: async ({ to, subject, text, html }) => {
+    const response = await fetch(`${baseURL}/emails`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ from, to: [to], subject, text, html }),
+    })
+    if (!response.ok) throw new Error(`Resend refused a message: ${response.status} ${response.statusText}`)
+  },
+})
+// mithaq-admin 0.0.0 37f2bedf34183fb350814b0e9f4a1453fb4f5491d359794f443461f04bf81e9e

package/template/templates/mithaq/src/mithaq/audit-sink.ts

@@ -0,0 +1,111 @@
+import type { AuditHandler } from 'mithaq'
+import { same } from 'mithaq/admin'
+
+/**
+ * The kayan this sink writes, which `./audit-log.ts` declares under the same
+ * name. A file of its own, apart from the kayan's, because the service target
+ * that holds this sink is built in `../mithaq.ts` and the kayan imports its
+ * `defineKayan` from there, so one file holding both would be a cycle.
+ */
+export const auditLogName = 'auditLog'
+
+/**
+ * One changed column: what it held before the write and what it holds after. A change one side of
+ * which was too long to keep whole is `truncated`: both sides are JSON text, the long one cut short.
+ */
+export type Change = { from: unknown; to: unknown; truncated?: true }
+
+/** How many characters of one side of a change an entry keeps: one large json value never swells the log. */
+export const keptLength = 2000
+
+const textOf = (value: unknown) => {
+  if (value === null) return null
+  // By code point, so the cut never leaves half of a surrogate pair, which Postgres refuses.
+  const points = [...JSON.stringify(value)]
+  return points.length > keptLength ? `${points.slice(0, keptLength).join('')}…` : points.join('')
+}
+// By code point, as `textOf` cuts, so a side is cut exactly when it is marked cut.
+const tooLong = (value: unknown) => [...(JSON.stringify(value) ?? '')].length > keptLength
+
+/**
+ * What the Activity panel draws as a dash: absent, `null`, an empty string or
+ * an empty list. A column that is one of these before and after changed
+ * nothing a reader could see.
+ */
+export const empty = (value: unknown) => value === undefined || value === null || value === '' || (Array.isArray(value) && !value.length)
+
+/**
+ * The columns whose value differs, each with its value on both sides and
+ * `null` for a side that held none. A column empty on both sides is no change,
+ * so a create lists only what it set and a delete only what the row held. A
+ * side longer than `keptLength` is kept as the start of its JSON.
+ */
+export const changesOf = (before: Readonly<Record<string, unknown>>, after: Readonly<Record<string, unknown>>) => {
+  const changes: Record<string, Change> = {}
+  for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (same(before[key], after[key]) || (empty(before[key]) && empty(after[key]))) continue
+    const [from, to] = [before[key] ?? null, after[key] ?? null]
+    // Both sides as JSON text where either is cut, so the panel reads a cut change one way.
+    changes[key] = tooLong(from) || tooLong(to) ? { from: textOf(from), to: textOf(to), truncated: true } : { from, to }
+  }
+  return changes
+}
+
+const rowOf = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  value && typeof value === 'object' && !Array.isArray(value) && 'id' in value ? (value as Record<string, unknown>) : undefined
+
+const stringOf = (value: unknown) => (typeof value === 'string' ? value : null)
+
+/**
+ * The service target's audit sink: one `auditLog` row per row a write changed,
+ * written through the store and the transaction the write itself runs in, so
+ * the entry commits with the change or not at all. It goes to the store and
+ * not through an operation, because the log declares none that writes: this is
+ * the only thing that writes it.
+ *
+ * A bulk runs every row through the single-row write of its effect, which
+ * audits that row, and then audits itself with the page of rows as its
+ * result; that second call names no row and is passed over here. An update
+ * that moved nothing but the columns the runner bumps on every write declines
+ * its own row. A delete of a kayan with no soft-delete field removes the row,
+ * so its change is every column to nothing; a soft delete hands back the row it
+ * marked, and its change is the mark.
+ *
+ * The actor is the person the write ran as, and `impersonatedBy` the real one
+ * behind an impersonated session. `mithaq rbac assign` hands the sink no person
+ * but the command and the operating-system user, and the entry names both. The
+ * organization is the one the row belongs to, which is the active one inside a
+ * managed write and the one the log is read in; a shared kayan writes no entry.
+ */
+export const auditSink: AuditHandler = async ({ effect, kayan, operation, dataBefore, dataAfter, store, tx, user }) => {
+  // A shared kayan writes no entry: the log is read in one organization alone,
+  // so an entry of none is one nobody reads, and the shared kayan are the
+  // provider's generated auth tables and local auth's accounts, whose rows hold
+  // tokens and hashes a log should never keep.
+  const owner = kayan.tenant
+  if (effect === 'read' || !store || kayan.name === auditLogName || !owner) return
+  const before = dataBefore ?? {}
+  const after = rowOf(dataAfter)
+  const record = after?.id ?? dataBefore?.id
+  if (record === undefined || record === null) return
+  const removed = effect === 'delete' && !kayan.softDelete
+  const changes = changesOf(before, removed ? {} : (after ?? {}))
+  if (effect === 'update' && Object.keys(changes).every((name) => kayan.fields[name]?.rules?.nowOnUpdate)) return
+  const actor = user && typeof user === 'object' ? (user as { id?: unknown; impersonatedBy?: unknown; command?: unknown; osUser?: unknown }) : undefined
+  await store.insert({ tx, kayan: auditLogName, data: {
+    createdAt: new Date(),
+    organization: stringOf(after?.[owner] ?? before[owner]),
+    kayan: kayan.name,
+    record: String(record),
+    // An update that took a draft to published is named a publish, as Payload's
+    // own history says it, so the Activity filters it apart from an edit.
+    operation: operation === 'update' && changes._status?.to === 'published' ? 'publish' : operation,
+    actor: stringOf(actor?.id) ?? (typeof actor?.command === 'string' ? `${actor.command} (${String(actor.osUser)})` : null),
+    impersonatedBy: stringOf(actor?.impersonatedBy),
+    // The object itself, a jsonb value. The log is never ordered by it, and
+    // searched by it only within the kayan whose columns its reader may be
+    // told of (`reachOf`), since a match in any other would tell a value its
+    // reader may not read.
+    changes,
+  } })
+}

package/template/templates/mithaq/src/mithaq/auth/backoffice-roles.ts

@@ -0,0 +1,108 @@
+import type { SystemRoles } from 'mithaq'
+
+/** One kayan read whole on the backoffice: its list, its count, one row, and each column named. */
+const reads = (kayan: string, fields: readonly string[]) => [`${kayan}.find`, `${kayan}.count`, `${kayan}.findByID`, ...fields.map((field) => `${kayan}.fields.${field}`)]
+const stamps = ['id', 'createdAt', 'updatedAt'] as const
+
+/**
+ * The columns of a kayan the backoffice lists that no staff role reads, each
+ * one a decision written down rather than a name left out. No backoffice role
+ * reads one, `super_admin`'s `'*'` included: the backoffice's row closes each
+ * by name whatever keys the actor holds.
+ */
+export const secret: readonly `${string}.fields.${string}`[] = [
+  // add-on: courses
+  // The code a live course's learners join with, a tenant's secret.
+  'courses.fields.accessCode',
+  // end add-on: courses
+]
+
+/**
+ * The kayan the backoffice lists that no staff role reads at all, a decision
+ * about the whole kayan rather than about its columns: no staff role holds a
+ * key of one, and only `super_admin`'s `'*'` lists it. `localUsers` is read
+ * and verified by a super admin alone, which the kayan's own access says, so a
+ * key here would grant support or explorer nothing, and its protected columns
+ * are closed to every reader by the provider.
+ */
+export const superAdminOnly = ['localUsers'] as const
+
+/** The people, the organizations and their members, which the provider owns. */
+const people = [
+  ...reads('user', [...stamps, 'name', 'email', 'emailVerified', 'image', 'role', 'banned', 'banReason', 'banExpires']),
+  ...reads('organization', [...stamps, 'name', 'names', 'slug', 'logo', 'metadata']),
+  ...reads('member', [...stamps, 'organizationId', 'userId', 'role', 'lastSeenAt']),
+]
+
+/** Each tenant's business, across every organization. */
+const business = [
+  // add-on: courses
+  // Every column but the one `secret` names.
+  ...reads('courses', [...stamps, 'organization', 'title', 'summary', 'details', 'cover', 'fee', 'currency', 'level', 'notifications', 'delivery', 'audience', 'archived', 'topics', 'opensOn', 'archiveReason', 'tags', 'scheduledSessions', '_status', 'selfEnroll']),
+  // A course's versions, each cut to the columns above, so staff read a
+  // draft's history across every organization and restore none of it: no
+  // staff role but `super_admin`'s `'*'` holds `courses.restoreVersion`.
+  'courses.findVersions',
+  'courses.findVersionByID',
+  ...reads('sessions', [...stamps, 'organization', 'course', 'startsAt', 'capacity', 'venue', 'format', 'archived', 'details', 'enrollments', 'archiveReason']),
+  ...reads('enrollments', [...stamps, 'organization', 'session', 'student', 'deletedAt']),
+  // end add-on: courses
+  ...reads('tags', [...stamps, 'organization', 'name']),
+]
+
+/** Who holds what inside each tenant: its role rows and its assignments. */
+const grants: string[] = [
+  // add-on: roles
+  ...reads('roles', [...stamps, 'organization', 'name', 'label', 'permissions']),
+  ...reads('memberRoles', [...stamps, 'organization', 'user', 'role']),
+  // end add-on: roles
+]
+
+/**
+ * The staff history: who impersonated whom, set whose backoffice role and banned whom. `super_admin`
+ * reads it by its `'*'` and `explorer` by these keys; never support, whose impersonations it records.
+ */
+const history: string[] = [
+  // add-on: audit-log
+  ...reads('backofficeLog', ['id', 'createdAt', 'action', 'actor', 'actorEmail', 'target', 'targetEmail', 'previousRole', 'role', 'banReason']),
+  // end add-on: audit-log
+]
+
+/**
+ * The backoffice roles: staff above every tenant, held on Better Auth's own
+ * `user.role` rather than on a tenant's assignment. The column may hold several,
+ * comma-separated, which is how the admin plugin reads it.
+ *
+ * Each holds catalog keys the way a tenant role does, and the access target
+ * holds them only in the backoffice app: in the tenant app an actor holds its
+ * membership's roles in its active organization and nothing of these. The
+ * admin plugin's own roles are built from the same lists below, so the routes
+ * that set a role, ban and impersonate refuse what the list does not name.
+ *
+ * `organization.rename` is this template's own statement, added beside these in
+ * `asas.ts`. Every read is a kayan's own keys: its list, its count and one row,
+ * and one key per column, since a backoffice role reads a column only where it
+ * holds that column's key. A project adds its own backoffice role, `billing` say,
+ * as one more entry here.
+ */
+export const backofficeRoles = {
+  /** Every key, and so the only role that grants a backoffice role, `user.set-role`, and renames an organization, `organization.rename`. */
+  super_admin: {
+    label: { ar: 'مدير لوحة الإدارة الخلفية', en: 'Backoffice administrator' },
+    permissions: '*',
+  },
+  /**
+   * Reads the people, the organizations and each tenant's business, and
+   * impersonates a tenant's user. It bans no one, sets no role, renames no
+   * organization, and reads no tenant's roles: it sees those by impersonating.
+   */
+  support: {
+    label: { ar: 'الدعم', en: 'Support' },
+    permissions: ['screen.backoffice', 'user.impersonate', ...people, ...business],
+  },
+  /** Reads everything on the backoffice, each tenant's roles and the staff history included, and changes nothing. */
+  explorer: {
+    label: { ar: 'مستكشف', en: 'Explorer' },
+    permissions: ['screen.backoffice', ...people, ...business, ...grants, ...history],
+  },
+} as const satisfies SystemRoles