@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/auth/better-auth/access.d.ts

@@ -0,0 +1,29 @@
+import type { RowTable } from '../../mithaq/rows.ts';
+import { type AccessOptions, type AccessTarget, type SystemRoles } from '../../rbac/index.ts';
+export type BetterAuthAccessOptions<Roles extends SystemRoles, Table extends RowTable, Actor> = AccessOptions<Roles, Table, Actor> & {
+    /** The provider's own compile-time roles, each an `ac.newRole(...)` result. */
+    statements?: Readonly<Record<string, {
+        statements: Readonly<Record<string, readonly string[]>>;
+    }>>;
+};
+/**
+ * The access target over Better Auth's own `member.role` and nothing else: a member holds the system
+ * roles its membership row names in that organization, comma-separated, and there is no custom role
+ * and no assignment table. It suits a project whose roles are the provider's owner, admin and member.
+ * The row is read from the store for the organization asked about, never off the session, so a
+ * membership elsewhere grants nothing here.
+ *
+ * A `member.role` slug is one a tenant's admin can mint, since the provider's dynamic access control
+ * is on, so `roles` holds only slugs a tenant may hold, or `rolesOf` drops the rest: a backoffice role
+ * named in it would otherwise grant its keys inside the tenant.
+ */
+export declare const memberRoleTarget: <const Roles extends SystemRoles, const Table extends RowTable, Actor>({ roles, rolesOf, access, }: Omit<AccessOptions<Roles, Table, Actor>, 'kayan'>) => AccessTarget<Roles, Table, Actor> & {
+    readonly type: 'memberRole';
+};
+/**
+ * The access target over Better Auth's store: a custom role is an `organizationRole` row.
+ * Read directly, not through `hasPermission`, whose cache never invalidates a narrowed role.
+ */
+export declare const betterAuthTarget: <const Roles extends SystemRoles, const Table extends RowTable, Actor>({ roles, rolesOf, access, kayan, statements, }: BetterAuthAccessOptions<Roles, Table, Actor>) => AccessTarget<Roles, Table, Actor> & {
+    readonly type: 'betterAuth';
+};

package/dist/auth/better-auth/access.js

@@ -0,0 +1,103 @@
+import { allRows, assignedSlugs, heldSlugs, rbacTarget, scoped, systemKeys } from '../../rbac/index.js';
+// An action list that is not a list of strings contributes nothing: a string
+// would flatten character by character.
+const flatten = (statements, into) => {
+    for (const [resource, actions] of Object.entries(statements)) {
+        if (!Array.isArray(actions))
+            continue;
+        for (const action of actions)
+            if (typeof action === 'string')
+                into.add(`${resource}.${action}`);
+    }
+};
+// Better Auth stores `permission` as a JSON string, not the record its zod object describes.
+const readPermission = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    for (const actions of Object.values(parsed)) {
+        if (!Array.isArray(actions) || actions.some((action) => typeof action !== 'string'))
+            return undefined;
+    }
+    return parsed;
+};
+/**
+ * The access target over Better Auth's own `member.role` and nothing else: a member holds the system
+ * roles its membership row names in that organization, comma-separated, and there is no custom role
+ * and no assignment table. It suits a project whose roles are the provider's owner, admin and member.
+ * The row is read from the store for the organization asked about, never off the session, so a
+ * membership elsewhere grants nothing here.
+ *
+ * A `member.role` slug is one a tenant's admin can mint, since the provider's dynamic access control
+ * is on, so `roles` holds only slugs a tenant may hold, or `rolesOf` drops the rest: a backoffice role
+ * named in it would otherwise grant its keys inside the tenant.
+ */
+export const memberRoleTarget = ({ roles, rolesOf, access, }) => ({
+    capability: 'access',
+    type: 'memberRole',
+    roles,
+    ...(rolesOf ? { rolesOf } : {}),
+    access: (access ?? {}),
+    // Better Auth's own model and columns.
+    reads: ['member'],
+    resolve: async ({ store, tenant, member, actor }) => {
+        // A read without a tenant would be every tenant's; the actor still goes through `rolesOf`, which
+        // answers backoffice staff, who have no active organization, their backoffice roles.
+        const found = scoped(tenant) && scoped(member)
+            ? await allRows({ store, kayan: 'member', where: { and: [{ organizationId: { equals: tenant } }, { userId: { equals: member } }] } })
+            : { docs: [] };
+        // Split the way the provider's own owner checks split it: exact, untrimmed, so ` owner` is no owner.
+        const slugs = [...new Set(found.docs.flatMap((row) => (typeof row.role === 'string' ? row.role.split(',').filter(Boolean) : [])))];
+        const held = heldSlugs({ roles, rolesOf, slugs, actor });
+        const { everything, keys } = systemKeys(roles, held);
+        return { permissions: everything ? '*' : [...keys], roles: held };
+    },
+});
+/**
+ * The access target over Better Auth's store: a custom role is an `organizationRole` row.
+ * Read directly, not through `hasPermission`, whose cache never invalidates a narrowed role.
+ */
+export const betterAuthTarget = ({ roles, rolesOf, access, kayan, statements = {}, }) => {
+    const base = rbacTarget({ access, kayan, roles, rolesOf });
+    const { memberRoles, roles: roleKayan } = kayan;
+    return {
+        ...base,
+        type: 'betterAuth',
+        reads: [roleKayan, memberRoles],
+        resolve: async ({ store, tenant, member, actor, ownership }) => {
+            const slugs = await assignedSlugs({ store, kayan: memberRoles, field: ownership(memberRoles), tenant, member });
+            const held = heldSlugs({ roles, rolesOf, slugs, actor });
+            const { custom, everything, keys } = systemKeys(roles, held);
+            if (everything)
+                return { permissions: '*', roles: slugs };
+            for (const slug of held) {
+                const role = statements[slug];
+                if (role?.statements)
+                    flatten(role.statements, keys);
+            }
+            if (custom.length && scoped(tenant)) {
+                // Caught, so a role table that is down loses the keys and not the assignment.
+                const found = await allRows({ store, kayan: roleKayan, where: {
+                        and: [{ organizationId: { equals: tenant } }, { role: { in: custom } }],
+                    } }).catch(() => undefined);
+                if (!found)
+                    return { permissions: [], roles: slugs };
+                const stored = found.docs.map((row) => readPermission(row.permission));
+                // A malformed column voids the whole answer.
+                if (stored.some((one) => one === undefined))
+                    return { permissions: [], roles: slugs };
+                for (const one of stored)
+                    flatten(one, keys);
+            }
+            return { permissions: [...keys], roles: slugs };
+        },
+    };
+};

package/dist/auth/better-auth/generate.d.ts

@@ -0,0 +1,31 @@
+import { getAuthTables } from 'better-auth/db';
+/**
+ * The first line of every file this generator writes. A file without it is the
+ * developer's, and is left exactly as it is.
+ */
+export declare const header = "// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.";
+/**
+ * Writes one kayan file per Better Auth table, and one barrel beside them. With `check`, writes
+ * nothing and returns the files a run would change or delete. A file without the header is never touched.
+ */
+export declare const generateAuth: ({ options, directory, language, check, provider, providers, screens, schemaName, }: {
+    options: Parameters<typeof getAuthTables>[0];
+    directory: URL;
+    /** The module each generated kayan imports `defineKayan` from: `generate.language`, as given. */
+    language: string;
+    check?: boolean;
+    /** The Postgres schema every kayan of this instance is built in, from its `providers` entry. */
+    schemaName?: string;
+    /** Each screen of the language by name, and the kayan it lists, which is where a title is written. */
+    screens?: Readonly<Record<string, readonly string[]>>;
+} & ({
+    provider?: undefined;
+    providers?: undefined;
+} | {
+    /** The kayan this instance authenticates, whose file carries the `auth` key. */
+    provider: string;
+    /** The module that file imports `providers` from: `generate.providers`, as given. */
+    providers: string;
+})) => Promise<string[]>;
+/** The auth generator as the CLI runs it. */
+export declare const run: (project: URL, check: boolean) => Promise<number>;

package/dist/auth/better-auth/generate.js

@@ -0,0 +1,328 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { isIdentifierName, isKeyword, isStrictBindReservedWord } from '@babel/helper-validator-identifier';
+import { getAuthTables } from 'better-auth/db';
+import { snakeCase } from '../../mithaq/resolve.js';
+import { isScreen } from '../../mithaq/language.js';
+import { Refusal } from '../../mithaq/refusal.js';
+const kinds = {
+    boolean: 'checkbox',
+    date: 'datetime',
+    number: 'number',
+    string: 'text',
+};
+const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const sourceString = (value) => `'${JSON.stringify(value).slice(1, -1).replaceAll("'", "\\'")}'`;
+const sourceKey = (name) => (identifier.test(name) ? name : sourceString(name));
+const databaseName = (name) => name.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').replace(/([a-z\d])([A-Z])/g, '$1_$2').toLowerCase();
+const exportName = (name) => {
+    if (!identifier.test(name) || !isIdentifierName(name) || isKeyword(name) || isStrictBindReservedWord(name, true)) {
+        throw new Refusal(`Better Auth model "${name}" cannot be a generated file or export name.`);
+    }
+    return name;
+};
+/**
+ * The first line of every file this generator writes. A file without it is the
+ * developer's, and is left exactly as it is.
+ */
+export const header = '// Written by `mithaq generate auth` from the Better Auth options generate.providers names. Do not edit.';
+const fieldSource = (name, field) => {
+    const fieldName = field.fieldName ?? name;
+    const dbName = databaseName(fieldName);
+    // Better Auth computes every `onUpdate` value; only a date is ours to bump.
+    const keys = [
+        field.required ? 'required: true' : '',
+        field.unique ? 'unique: true' : '',
+        // Better Auth's own migrations build it, so leaving it out would have the next migrate drop it.
+        // A unique column's constraint is already its index.
+        field.index && !field.unique ? 'index: true' : '',
+        field.onUpdate && field.type === 'date' ? 'nowOnUpdate: true' : '',
+        field.onUpdate ? "providedBy: { update: 'application' }" : '',
+    ];
+    const rules = keys.filter(Boolean).join(', ');
+    if (field.references) {
+        // An explicit dbName keeps the relationship from becoming `user_id_id`. A required
+        // foreign key is ownership: a user's sessions and accounts go when the user goes.
+        const onDelete = field.required ? `onDelete: 'cascade'` : '';
+        const bindings = [rules, onDelete].filter(Boolean).join(', ');
+        return `  ${sourceKey(fieldName)}: { kind: 'relationship', relationTo: () => ${exportName(field.references.model)}, dbName: ${sourceString(dbName)}${bindings ? `, rules: { ${bindings} }` : ''} },`;
+    }
+    const kind = kinds[field.type];
+    if (!kind) {
+        throw new Refusal(`Better Auth field "${name}" has type "${field.type}", which mithaq has no kind for. Add one to the kinds map in auth/better-auth/generate.ts.`);
+    }
+    const named = dbName === snakeCase(fieldName) ? '' : `, dbName: ${sourceString(dbName)}`;
+    return `  ${sourceKey(fieldName)}: { kind: '${kind}'${named}${rules ? `, rules: { ${rules} }` : ''} },`;
+};
+const kayanSource = ({ name, table, language, provider, providers, screens = {}, access = false, operations = false, drawn, schemaName, idKind, }) => {
+    const exported = exportName(name);
+    // Written only under screens that list the kayan: a `targets.<screen>` on a kayan
+    // the screen does not list is refused at build.
+    const title = table.fields.name && (table.fields.name.fieldName ?? 'name');
+    const modelName = table.modelName ?? name;
+    const dbName = databaseName(modelName);
+    const titled = title
+        ? Object.entries(screens)
+            .filter(([screen, kayan]) => kayan.includes(modelName) && !drawn?.includes(screen))
+            .map(([screen]) => `, ${sourceKey(screen)}: { useAsTitle: ${sourceString(title)} }`)
+            .join('')
+        : '';
+    const references = [
+        ...new Set(Object.values(table.fields)
+            .map((field) => field.references?.model)
+            .filter((model) => model !== undefined && model !== name)),
+    ].sort();
+    const carries = provider !== undefined && provider === modelName;
+    const key = identifier.test(provider ?? '') ? `.${provider}` : `[${sourceString(provider ?? '')}]`;
+    const imports = [
+        `import { betterAuth, defaultFields, defaultOperations } from 'mithaq'`,
+        `import { defineKayan } from ${sourceString(language)}`,
+        ...(carries ? [`import { providers } from ${sourceString(providers ?? '')}`] : []),
+        ...references.map((model) => `import { ${exportName(model)} } from './${exportName(model)}.ts'`),
+        ...(access ? [`import { access } from './${exported}.access.ts'`] : []),
+        ...(operations ? [`import { operations } from './${exported}.operations.ts'`] : []),
+        ...(drawn ? [`import { screens } from './${exported}.screens.ts'`] : []),
+    ];
+    if (!carries)
+        imports[0] = `import { defaultFields, defaultOperations } from 'mithaq'`;
+    const operationSource = operations ? '{ ...defaultOperations, ...operations }' : 'defaultOperations';
+    return `${header}
+// This kayan's access and what each screen draws of it are the project's:
+// \`${exported}.access.ts\` exporting \`access\` and \`${exported}.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.
+${imports.join('\n')}
+
+export const ${exported} = defineKayan({
+  name: ${sourceString(modelName)}${dbName === modelName ? '' : `,
+  dbName: ${sourceString(dbName)}`},${schemaName === undefined ? '' : `
+  schemaName: ${sourceString(schemaName)},`}${carries ? `
+  auth: betterAuth({ server: providers${key}.server }),` : ''}
+  targets: { ${drawn ? `${titled.slice(2)}${titled ? ', ' : ''}...screens, service: { operations: ${operationSource} }` : `service: { operations: ${operationSource} }${titled}`} },${access ? `
+  access,` : ''}
+  fields: {
+    ...defaultFields,
+    id: { kind: '${idKind}' },
+${Object.entries(table.fields)
+        .map(([field, definition]) => `  ${fieldSource(field, definition)}`)
+        .join('\n')}
+  },
+})
+`;
+};
+const readFolder = (folder) => readdir(folder, { withFileTypes: true }).catch((error) => {
+    if (error.code === 'ENOENT')
+        return [];
+    throw error;
+});
+const barrelName = 'index';
+// A plugin that only adds fields to `user` or `session` names those tables in its
+// schema too, so the tables Better Auth ships with no plugin are subtracted.
+const barrelSource = (options, tables) => {
+    const shipped = new Set(Object.keys(getAuthTables({})));
+    const claimed = new Map();
+    const plugins = options.plugins ?? [];
+    for (const plugin of plugins) {
+        if (!plugin?.id || !plugin.schema)
+            continue;
+        for (const table of Object.keys(plugin.schema)) {
+            if (shipped.has(table) || claimed.has(table))
+                continue;
+            claimed.set(table, plugin.id);
+        }
+    }
+    const groups = new Map([['core', []]]);
+    for (const table of tables) {
+        const key = claimed.get(table) ?? 'core';
+        groups.set(key, [...(groups.get(key) ?? []), exportName(table)]);
+    }
+    const barrelImports = [...tables].map((table) => exportName(table)).sort();
+    return `${header}
+// 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.
+${barrelImports.map((one) => `import { ${one} } from './${one}.ts'`).join('\n')}
+
+export const betterAuth = {
+${[...groups].map(([key, list]) => `  ${sourceKey(key)}: [${list.join(', ')}],`).join('\n')}
+} as const
+`;
+};
+/**
+ * Writes one kayan file per Better Auth table, and one barrel beside them. With `check`, writes
+ * nothing and returns the files a run would change or delete. A file without the header is never touched.
+ */
+export const generateAuth = async ({ options, directory, language, check = false, provider, providers, screens, schemaName, }) => {
+    const tables = getAuthTables(options);
+    const names = Object.keys(tables);
+    // With a `uuid` id, Better Auth's pg adapter leaves the id out of the insert and the
+    // column's `defaultRandom` fills it; a text kayan under a uuid instance fails every insert.
+    const idKind = options.advanced?.database?.generateId === 'uuid' ? 'uuid' : 'text';
+    if (names.includes(barrelName)) {
+        throw new Refusal(`Better Auth model "${barrelName}" would be written to the same file as the barrel this generator writes. Rename the model.`);
+    }
+    // The whole directory is read before anything is written or removed, so a file
+    // that stops the run stops it before the first deletion.
+    if (!check)
+        await mkdir(directory, { recursive: true });
+    const files = (await readFolder(directory)).map((entry) => entry.name);
+    // Sibling access, screens and operations files are the project's way in: the
+    // generated file is the generator's.
+    const siblings = new Set(files.filter((file) => file.endsWith('.access.ts') || file.endsWith('.screens.ts') || file.endsWith('.operations.ts')));
+    // Read by importing it: a title written beside a block the sibling also writes is
+    // one the compiler refuses as overwritten.
+    const drawnBy = new Map();
+    for (const file of siblings) {
+        if (!file.endsWith('.screens.ts'))
+            continue;
+        const exported = (await import(__rewriteRelativeImportExtension(new URL(file, directory).href))).screens;
+        drawnBy.set(file, exported && typeof exported === 'object' ? Object.keys(exported) : []);
+    }
+    const wanted = new Map(Object.entries(tables).map(([name, table]) => [
+        `${name}.ts`,
+        kayanSource({ name, table: table, language, provider, providers, screens, access: siblings.has(`${name}.access.ts`), operations: siblings.has(`${name}.operations.ts`), drawn: drawnBy.get(`${name}.screens.ts`), schemaName, idKind }),
+    ]));
+    // Otherwise the `auth` key would be written onto nothing.
+    const named = Object.entries(tables).some(([name, table]) => (table.modelName ?? name) === provider);
+    if (provider !== undefined && !named) {
+        throw new Refusal(`No Better Auth table of the "${provider}" instance is named "${provider}", so there is no kayan for its \`auth\` to sit on. Name the instance after the table its sessions belong to, which is \`user\` unless its options rename it.`);
+    }
+    wanted.set(`${barrelName}.ts`, barrelSource(options, names));
+    const changed = [];
+    const stale = [];
+    const theirs = [];
+    for (const file of files) {
+        if (!file.endsWith('.ts'))
+            continue;
+        const current = await readFile(new URL(file, directory), 'utf8');
+        if (wanted.has(file)) {
+            if (!current.startsWith(header))
+                theirs.push(file);
+            else if (current === wanted.get(file))
+                wanted.delete(file);
+            continue;
+        }
+        if (current.startsWith(header))
+            stale.push(file);
+    }
+    if (theirs.length) {
+        throw new Refusal(theirs.length > 1
+            ? `${theirs.sort().join(', ')} were not written by \`mithaq generate auth\` and generating would overwrite them. Move them or delete them.`
+            : `${theirs[0]} was not written by \`mithaq generate auth\` and generating would overwrite it. Move it or delete it.`);
+    }
+    for (const file of stale) {
+        changed.push(file);
+        if (!check)
+            await rm(new URL(file, directory));
+    }
+    for (const [file, source] of wanted) {
+        changed.push(file);
+        if (!check)
+            await writeFile(new URL(file, directory), source);
+    }
+    return changed.sort();
+};
+/** The auth generator as the CLI runs it. */
+export const run = async (project, check) => {
+    const { generate, targets } = (await import(__rewriteRelativeImportExtension(new URL('src/mithaq.ts', project).href)));
+    const screens = Object.fromEntries(Object.entries(targets ?? {}).flatMap(([name, target]) => (isScreen(target) ? [[name, target.kayan]] : [])));
+    // Where the files go is the project's choice, so nothing stands in for a folder it left out.
+    const folder = generate?.auth;
+    if (typeof folder !== 'string') {
+        throw new Refusal("src/mithaq.ts names no `generate.auth`, which is the folder this generator writes the Better Auth kayan into. Add `auth: '<folder>'` to `generate`, such as `auth: 'src/kayan/auth/'`.");
+    }
+    const root = new URL(folder, project);
+    // Resolved from where the generated files sit, since each imports it exactly as written.
+    const from = generate?.providers;
+    if (typeof from !== 'string') {
+        throw new Refusal(`src/mithaq.ts names no \`generate.providers\`, which is the module this generator reads \`providers\` from and writes into each generated kayan's import. Add \`providers: '<package name, or a path relative to a generated file>'\` to \`generate\`, beside \`auth: ${sourceString(folder)}\`.`);
+    }
+    // Resolved under `require`'s conditions, because `import.meta.resolve` takes no
+    // parent without a flag on Node 24.
+    let resolved;
+    try {
+        resolved = createRequire(new URL('instance/index.ts', root)).resolve(from);
+    }
+    catch (error) {
+        if (error.code !== 'MODULE_NOT_FOUND')
+            throw error;
+        throw new Refusal(`\`generate.providers\` names "${from}", which cannot be found from a generated file under ${sourceString(folder)}. Name a package this project depends on, or a path relative to a generated file.`);
+    }
+    // The language sits wherever the project's layout puts it, a package or a file, so nothing stands in for it either.
+    const language = generate?.language;
+    if (typeof language !== 'string') {
+        throw new Refusal(`src/mithaq.ts names no \`generate.language\`, which is the module each generated kayan imports \`defineKayan\` from. Add \`language: '<package name, or a path relative to a generated file>'\` to \`generate\`, beside \`auth: ${sourceString(folder)}\`.`);
+    }
+    try {
+        createRequire(new URL('instance/index.ts', root)).resolve(language);
+    }
+    catch (error) {
+        if (error.code !== 'MODULE_NOT_FOUND')
+            throw error;
+        throw new Refusal(`\`generate.language\` names "${language}", which cannot be found from a generated file under ${sourceString(folder)}. Name the language's package, or a path relative to a generated file.`);
+    }
+    const { providers } = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href)));
+    if (!providers) {
+        throw new Refusal(`${from} exports no \`providers\`, which is the record this generator reads: one key per kayan a Better Auth instance authenticates, each \`{ options, server }\`.`);
+    }
+    // Checked for every entry before any instance's files are written.
+    for (const [provider, { schemaName }] of Object.entries(providers)) {
+        if (schemaName === undefined || typeof schemaName === 'string')
+            continue;
+        // `JSON.stringify` throws on a BigInt and answers `undefined` for a function.
+        let shown;
+        try {
+            shown = JSON.stringify(schemaName) ?? String(schemaName);
+        }
+        catch {
+            shown = String(schemaName);
+        }
+        throw new Refusal(`${from} gives the "${provider}" instance the schemaName ${shown}, and a schemaName is the name of a Postgres schema, a string such as 'auth'.`);
+    }
+    const changed = [];
+    for (const [provider, one] of Object.entries(providers)) {
+        const schemaName = one.schemaName;
+        const files = await generateAuth({ options: one.options, directory: new URL(`${provider}/`, root), language, check, provider, providers: from, screens, schemaName });
+        changed.push(...files.map((file) => `${provider}/${file}`));
+    }
+    // A directory of an instance no longer declared is reported, never removed: the
+    // generator owns the files it wrote, not the directory holding them.
+    if (!check)
+        await mkdir(root, { recursive: true });
+    const stale = [];
+    for (const entry of await readFolder(root)) {
+        if (!entry.isDirectory() || Object.hasOwn(providers, entry.name))
+            continue;
+        const barrel = await readFile(new URL(`${entry.name}/${barrelName}.ts`, root), 'utf8').catch(() => '');
+        if (barrel.startsWith(header))
+            stale.push(`${entry.name}/`);
+    }
+    const report = () => {
+        if (!stale.length)
+            return;
+        const sentence = `${stale.join(', ')} ${stale.length > 1 ? 'are directories' : 'is a directory'} of an instance ${from} no longer declares. Delete ${stale.length > 1 ? 'them' : 'it'}: this command never removes a directory.`;
+        if (check)
+            console.error(sentence);
+        else
+            console.log(sentence);
+    };
+    if (check && (changed.length || stale.length)) {
+        if (changed.length)
+            console.error(`Stale auth kayan: ${changed.join(', ')}. Run \`mithaq generate auth\`.`);
+        report();
+        return 1;
+    }
+    console.log(changed.length ? `Wrote ${changed.join(', ')}.` : 'Auth kayan are up to date.');
+    report();
+    return 0;
+};

package/dist/auth/better-auth/index.d.ts

@@ -0,0 +1,94 @@
+import { type AssignedResolver } from '../../asas/actor.ts';
+type BetterAuthUser = Record<string, unknown>;
+type BetterAuthOrganization = {
+    id: string;
+} & Record<string, unknown>;
+type BetterAuth = {
+    api: {
+        getSession(args: {
+            headers: Headers;
+            query?: {
+                disableRefresh?: boolean;
+            };
+        }): Promise<null | {
+            session?: BetterAuthUser;
+            user: BetterAuthUser;
+        }>;
+        getActiveMemberRole?(args: {
+            headers: Headers;
+        }): Promise<null | {
+            role?: unknown;
+        }>;
+        listOrganizations?(args: {
+            headers: Headers;
+        }): Promise<BetterAuthOrganization[]>;
+    };
+    handler(request: Request): Promise<Response>;
+};
+type SessionUser<Server extends BetterAuth> = NonNullable<Awaited<ReturnType<Server['api']['getSession']>>>['user'];
+export type BetterAuthActor<User extends BetterAuthUser = BetterAuthUser, Collection extends string = string> = User & {
+    activeOrganizationId?: unknown;
+    collection: Collection;
+    /** The real person behind an impersonated session, so the audit names who really made the write. */
+    impersonatedBy?: unknown;
+    /** The provider's own `member.role` in the active organization; several roles are comma-separated. */
+    memberRole?: string;
+    organizations?: BetterAuthOrganization[];
+    /** The ids of `organizations`, so a row can say `{ organization: { in: user.organizationIds } }`. */
+    organizationIds?: string[];
+    /** The keys the build's access target resolved for this actor, never a column of the provider's user row. */
+    permissions?: '*' | readonly string[];
+    /** The role slugs the access target resolved in the active tenant, never read from `member.role`. */
+    roles?: readonly string[];
+    strategy: 'better-auth';
+    user: User;
+};
+/**
+ * Whether the caller of the Better Auth request being handled holds `key`, for a project's
+ * `organizationHooks.before*`. Only a request through `asas.handler` is gated; any other call answers `true`.
+ */
+export declare const holdsPermission: (key: string) => boolean;
+/**
+ * The organization whose keys `holdsPermission` answers with. A provider route may act on another
+ * organization than the session's active one, so a hook compares the two first.
+ */
+export declare const requestOrganization: () => string | null | undefined;
+/** Better Auth as one strategy among siblings. The package never imports better-auth; the app owns it. */
+export declare const betterAuthStrategy: <Server extends BetterAuth, Collection extends string = string>({ server, collection, assigned, onError, }: {
+    server: Server;
+    collection: Collection;
+    assigned?: AssignedResolver;
+    /** Handed an access target that failed to answer, and a session read that failed. */
+    onError: (error: unknown) => void;
+}) => {
+    name: Collection;
+    authenticate: ({ headers }: {
+        headers: Headers;
+    }) => Promise<{
+        user: null;
+    } | {
+        user: BetterAuthActor<SessionUser<Server>, Collection>;
+    }>;
+    handler: (request: Request) => Promise<Response>;
+    /** The Better Auth instance, so the app can call `api.signUpEmail` and friends. */
+    server: Server;
+};
+/**
+ * The Better Auth provider as a kayan declares it. `server` is a factory, built from the
+ * targets and vocabulary the build derives; two kayan carrying this are two instances.
+ */
+export declare const betterAuth: <Server extends BetterAuth, Targets = unknown>(declaration: {
+    server: (targets: Targets, vocabulary: {
+        catalog: readonly string[];
+        statements: Readonly<Record<string, readonly string[]>>;
+        referenced: (id: string) => Promise<number>;
+    }) => Server;
+}) => {
+    provider: 'better-auth';
+    server: (targets: Targets, vocabulary: {
+        catalog: readonly string[];
+        statements: Readonly<Record<string, readonly string[]>>;
+        referenced: (id: string) => Promise<number>;
+    }) => Server;
+};
+export {};