@drhomet/mithaq 0.1.1 → 0.2.1

package/LICENSES/openstatus-time-picker.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OpenStatus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# mithaq
+
+[![npm](https://img.shields.io/npm/v/@drhomet/mithaq)](https://www.npmjs.com/package/@drhomet/mithaq)
+
+mithaq is a TypeScript language for declaring a backend and its admin once, and building the database, API, validation, access rules and admin screens from that one declaration.
+
+The package is `@drhomet/mithaq`. It is pre-1.0, so the API may still change between releases.
+
+The name is Arabic for a covenant. The other words in the API are Arabic too, and each is defined where it first appears below.
+
+## Why it exists
+
+- **One declaration drives everything.** A kayan's fields, kinds and rules become the Postgres table (through drizzle), the input schema (through zod), the HTTP operations and the admin forms and lists. Nothing is declared twice, so nothing drifts.
+- **The vocabulary is frozen.** The kinds, rules and targets mithaq ships change only by the maintainer's explicit decision. A project can also seal its own language in a signed `mithaq.lock`. `mithaq lock --check`, which the apps run before `dev`, `build` and `preview`, then fails when the vocabulary no longer matches the lock. Signing a change takes a code shown in a popup, never in the command's output, so a script or an agent running `mithaq lock` cannot approve it.
+- **Tenant isolation is enforced in core.** A kayan that places the tenant field belongs to one organization. Core adds the tenant scope to every operation and combines it with the project's own access with AND, so no access rule can widen it. Writes land in the active organization, and `unique` rules and index groups are built per organization.
+- **Defaults are explicit.** The project names every default it uses (`defaultOperations`, `defaultFields`, `defaultAuthorize`, the limits) in its own code. Core does not fall back to a default of its own: a configuration that leaves a required one out is a type error or a refusal from `buildAsas`.
+- **The admin is your code when you want it.** The screens are shadcn components the project imports from `mithaq-admin` and draws with its own primitives; `mithaq eject` puts any one of them into the project to edit like any other file.
+
+## Quick start
+
+```sh
+bun create mithaq my-app --full
+```
+
+This creates a Bun workspace of the template's three steps, the language (`packages/mithaq`), a package per feature (`packages/features/*`) and the asas that builds them (`packages/asas`), and two apps: the tenant app (`apps/asas-tanstack`), which serves the dashboard and the portal, and the backoffice console (`apps/asas-backoffice`), for staff who work across every organization. It writes a `.env` with fresh secrets and runs `bun install`. `--full` takes every add-on, the whole worked example; without it the project is minimal, auth and a `tags` example, and `--with roles,courses` picks add-ons.
+
+Then, with PostgreSQL 15 or later serving the database that `DATABASE_URL` names in `packages/asas/.env`:
+
+```sh
+cd my-app
+cd packages/asas
+# push the schema, make the dev admin and fill its organization, development only
+bun run dev:setup --seed
+cd ../..
+bun run --cwd apps/asas-tanstack dev   # the tenant app, http://localhost:5173
+bun run --cwd apps/asas-backoffice dev   # in a second terminal: the backoffice console, http://localhost:5174
+```
+
+Sign in to both apps with `DEV_ADMIN_EMAIL` and `DEV_ADMIN_PASSWORD` from `packages/asas/.env`: the dev admin owns "Dev admin's workspace", which `--seed` filled, and is the backoffice's `super_admin`.
+
+In production, `connect()` does not push the schema; it checks the migration files instead. [Running in production](https://github.com/drhomet/mithaq/blob/main/templates/asas/README.md#running-in-production) explains how to apply them.
+
+## A small example
+
+A language comes from `defineMithaq`. Its arkan (singular rukn, "pillar") are the pluggable parts that bring kinds and rules; `base` brings the shipped ones. Its targets are what each declaration is built into.
+
+```ts
+// src/mithaq.ts
+import {
+  base, defaultAuthorize, defaultBulkLimit, defaultDepth, defaultJoinLimit, defaultLimit, defaultMaxLimit,
+  defineMithaq, drizzleAdapter, drizzleKinds, drizzleRules, drizzleIdKinds, serviceTarget, zodKinds, zodRules, zodIdKinds, zodTarget,
+} from 'mithaq'
+
+export const { defineKayan, buildAsas } = defineMithaq({
+  locales: ['en', 'ar'] as const,
+  arkan: [base],
+  targets: {
+    drizzle: drizzleAdapter({ connectionString: process.env.DATABASE_URL!, kinds: drizzleKinds, rules: drizzleRules, idKinds: drizzleIdKinds }),
+    zod: zodTarget({ kinds: zodKinds, rules: zodRules, idKinds: zodIdKinds }),
+    service: serviceTarget({
+      authorize: defaultAuthorize,
+      depth: defaultDepth,
+      defaultLimit,
+      maxLimit: defaultMaxLimit,
+      joinLimit: defaultJoinLimit,
+      bulkLimit: defaultBulkLimit,
+      store: 'drizzle',
+      schema: 'zod',
+    }),
+  },
+})
+```
+
+A kayan ("entity") is one data type: its fields, their kinds and rules, its access and its operations. Every label carries one string per locale the language declares, and a missing one is a type error.
+
+```ts
+// src/tags.ts
+import { defaultFields, defaultOperations } from 'mithaq'
+import { defineKayan } from './mithaq.ts'
+
+export const tags = defineKayan({
+  name: 'tags',
+  access: { read: () => true },
+  targets: { service: { operations: defaultOperations } },
+  fields: {
+    ...defaultFields,
+    name: {
+      kind: 'text',
+      label: { en: 'Name', ar: 'الاسم' },
+      rules: { required: true, unique: true, trim: true, maxLength: 60 },
+    },
+  },
+})
+```
+
+`buildAsas` builds the asas ("foundation"), the runtime:
+
+```ts
+// src/asas.ts
+import { defaultMaxBodyBytes, fetchHttp } from 'mithaq'
+import { buildAsas } from './mithaq.ts'
+import { tags } from './tags.ts'
+
+export const asas = buildAsas({ kayan: [tags], http: [fetchHttp({ maxBodyBytes: defaultMaxBodyBytes, onError: console.error })] })
+```
+
+`asas.handler(request)` answers a `Request` with a `Response`; mount it under `/api` in any server. With `fetchHttp`, `POST /api/tags/create` with a JSON body creates a tag, and `POST /api/tags/find` lists them. In development, `asas.connect()` pushes the schema to Postgres. A kayan that declares no access answers only the admin the build names, so this one opens reads to everyone.
+
+To make a kayan belong to one organization, add the tenant target to the language and place its field:
+
+```ts
+// in defineMithaq's targets:
+tenant: betterAuthTenant({ relationTo: 'organization', onDelete: 'restrict', newRows: 'active', organizations: 'many' }),
+
+// in a kayan's fields, with `tenant` taken from the language's `targets`:
+organization: tenant.field,
+```
+
+`unique: true` on that kayan is then unique within each organization, and `indexes: [{ within: 'organization', unique: [['code', 'term']] }]` declares a compound one. [Tenancy](https://github.com/drhomet/mithaq/blob/main/packages/mithaq/src/asas/runner/README.md) has the full rules.
+
+## What's in the box
+
+- **Store:** Postgres through drizzle (`drizzleAdapter`), with a schema push in development and migration files written by `mithaq migrate` for production.
+- **Validation:** zod schemas derived from every kayan (`zodTarget`). A field can carry its own zod shape instead.
+- **Runtime:** the operation runner (`serviceTarget`) with the default operations (create, update, delete, find, findByID, count, updateMany, deleteMany), steps around every write, an audit step, soft delete and bulk limits.
+- **HTTP:** plain fetch routes (`fetchHttp`), or a typed client and OpenAPI through oRPC (`mithaq/orpc`).
+- **Access:** role-based access with permission keys per operation and per field (`rbacTarget`, `betterAuthTarget` to keep roles in Better Auth's own tables, or `memberRoleTarget` for Better Auth's own member roles alone).
+- **Tenancy:** `betterAuthTenant`, over Better Auth organizations.
+- **Auth:** Better Auth (`betterAuth`) or local accounts (`local`), with `mithaq generate auth` writing the Better Auth kayan.
+- **Versions and drafts:** the `versions` rukn keeps a row's past versions, with drafts, autosave and restore.
+- **Files:** the `storage` rukn and the `upload` kind. The template ships adapters for local disk, Cloudflare R2, S3-compatible services and UploadThing as project files.
+- **Rich text:** the `richText` rukn, over Lexical.
+- **Admin screens:** `screenTarget` describes each screen; `mithaq generate screens` writes its routes into the host app, and the React components come from the `mithaq-admin` package, drawn with the app's own shadcn primitives, and a project ejects the ones it wants to own. `mithaq upgrade --check` compares the files it holds with the installed version.
+- **Copy:** `mithaq generate messages` writes the project's labels and messages to one file per kayan, and refuses a label missing a locale.
+
+`mithaq --help` lists every command.
+
+## Requirements
+
+- npm, pnpm 10.6 or later, Yarn 1 or [Bun](https://bun.sh) 1.3, whichever runs `create mithaq`. Yarn 2 and later install a copy of mithaq for each workspace of a monorepo, which the build refuses, so a monorepo does not take them yet.
+- Node.js 24 or later.
+- PostgreSQL 15 or later.
+- TypeScript, installed by the project.
+
+## Documentation
+
+Each guide is the `README.md` of the folder it describes.
+
+- [Working in a mithaq project](https://github.com/drhomet/mithaq/blob/main/templates/asas/README.md): getting started, where each file lives, adding a kayan, a feature or a step, and running in production. It ships in every created project.
+- [The mithaq language](https://github.com/drhomet/mithaq/blob/main/packages/mithaq/README.md): the language, kinds, rules, kayan, targets, the runner and access, and adding a rukn, a kind, a target or a configurable feature.
+- [Tenancy](https://github.com/drhomet/mithaq/blob/main/packages/mithaq/src/asas/runner/README.md): per-organization kayan, what core enforces, and per-organization indexes.
+- [The `mithaq` command](https://github.com/drhomet/mithaq/blob/main/packages/mithaq/src/asas/cli/README.md): every command, flag and exit code.
+- [Migrations in production](https://github.com/drhomet/mithaq/blob/main/packages/mithaq/src/drizzle/README.md): `pending: 'refuse'` or `'run'`, the advisory lock, and applying migrations by hand.
+- [The admin package](https://github.com/drhomet/mithaq/blob/main/packages/mithaq-admin/README.md): the screen components, ejecting one, `mithaq upgrade --check`, migrating a project that holds copies, and adding a registry item.
+- [Contributing](https://github.com/drhomet/mithaq/blob/main/CONTRIBUTING.md): setting up, the checks, the repository layout, and sending a pull request.
+
+## Status and license
+
+mithaq is pre-1.0. The template that `bun create mithaq` creates is the worked example, and every file there is commented.
+
+MIT licensed; see [LICENSE](https://github.com/drhomet/mithaq/blob/main/LICENSE). mithaq includes code adapted from Payload and from openstatus's time picker, both MIT licensed; their notices are in [LICENSES/payload.txt](https://github.com/drhomet/mithaq/blob/main/LICENSES/payload.txt) and [LICENSES/openstatus-time-picker.txt](https://github.com/drhomet/mithaq/blob/main/LICENSES/openstatus-time-picker.txt).

package/dist/asas/build.d.ts

@@ -111,6 +111,12 @@ type AdminAccessShapeMismatch<Auth> = Auth extends {
 export type Vocabulary = {
     catalog: readonly string[];
     statements: Readonly<Record<string, readonly string[]>>;
+    /**
+     * How many rows, across every organization, still name the auth kayan's row `id` through a
+     * relationship that restricts its delete. A provider route that deletes a person outside a
+     * transaction asks it first, since the foreign key would fail only after other rows went.
+     */
+    referenced: (id: string) => Promise<number>;
 };
 /** The build's auth: the admin kayan whose actor passes default access, and where failures are reported. */
 export type AuthConfig = {
@@ -121,6 +127,8 @@ export type AuthConfig = {
     };
     /** Handed a strategy that threw and an access target that could not answer, each as an `Error` with the cause. Required where any kayan carries auth. */
     onError: (error: unknown) => void;
+    /** The largest body an auth route reads, answered 413 past it: `defaultMaxBodyBytes` or the project's own. Required where any kayan carries auth. */
+    maxBodyBytes: number;
 };
 type PublicLocalUser<K extends Kayan, L extends Language, KayanList extends readonly Kayan[]> = Omit<Row<K['fields'], L, KayanList>, ProtectedLocalField>;
 /** One strategy per kayan carrying `auth`, typed by that provider's or that strategy's own actor. */
@@ -186,7 +194,7 @@ export declare const buildAsas: <const L extends Language, const KayanList exten
     auth?: Auth;
     /**
      * The HTTP plugs, asked in order, so the order decides who owns a prefix two claim. Required:
-     * `fetchHttp()` takes no dependency; `orpcHttp()` first gives `asas.router` its typed client.
+     * `fetchHttp` takes no dependency; `orpcHttp` first gives `asas.router` its typed client.
      */
     http: readonly [(operations: OperationTable<Procedures<KayanList, GlobalList, Declared<KayanList, GlobalList>, L>>) => Http, ...((operations: OperationTable<Procedures<KayanList, GlobalList, Declared<KayanList, GlobalList>, L>>) => HttpPlug)[]];
     /** The project's own copy for the labels mithaq ships, as one resolver whose return shape mithaq declares. */
@@ -202,7 +210,7 @@ export declare const buildAsas: <const L extends Language, const KayanList exten
     statements: Readonly<Record<string, readonly string[]>>;
     /** Every built operation, flat. Its `procedures` view is a type, keyed by kayan then operation. */
     operations: OperationTable<Procedures<KayanList, GlobalList, Declared<KayanList, GlobalList>, L>>;
-    /** The router the first plug built, which a typed client is built from; `undefined` for `fetchHttp()`. */
+    /** The router the first plug built, which a typed client is built from; `undefined` for `fetchHttp`. */
     router: Http['router'];
     /** Every target as the language passed it, so `asas.targets.drizzle.db` is drizzle. A screen also carries its projection under `client`. */
     targets: { [Name in keyof L['targets']]: L['targets'][Name] extends {

package/dist/asas/build.js

@@ -5,10 +5,11 @@ import { holdsVerificationSteps, isLocalAuthTarget, localAuthStrategy } from '..
 import { bulkSeals, outputOf, sealOf, storeSeals } from './runner/steps.js';
 import { running } from './runner/runtime.js';
 import { tenancy } from './runner/tenant.js';
-import { assertWhere, defaultAccess, defaultAuthorize, projectReadableFields } from './runner/write.js';
+import { assertWhere, defaultAccess, defaultAuthorize, projectReadableFields, referencingIds, restrictingPointers } from './runner/write.js';
 import { combineWhere } from '../mithaq/where.js';
 import { bulk, read as readers, write } from '../service/index.js';
 import { invalid } from './runner/errors.js';
+import { assertMaxBodyBytes, boundedBody } from './http/fetch.js';
 import { fieldlessOperation, keepOperationKeys } from '../rbac/steps.js';
 import { resolvedKayans } from '../mithaq/types.js';
 import { accessTargetOf, isAccess, isScreen, isService, isStorage, isStore, isTenant, isVersions, serviceKeys, serviceTargetOf } from '../mithaq/language.js';
@@ -16,6 +17,15 @@ import { screensOf } from '../screen/index.js';
 import { messagesOf } from '../mithaq/messages.js';
 import { resolve } from '../mithaq/resolve.js';
 import { recordStorage, resolveStorage, storageRoutes } from '../storage/storage.js';
+const lowerCase = (value) => typeof value === 'string' ? value.toLowerCase() : Array.isArray(value) ? value.map(lowerCase) : value;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// The parse lower-cases a uuid, as Postgres answers one, but access and the steps before the
+// transaction run ahead of it, so a JS comparison there must see the same spelling.
+const lowerUuids = ({ kayan, input, bulk }) => {
+    const fields = (data) => Object.fromEntries(Object.entries(data).map(([key, value]) => [key, kayan.fields[key]?.kind === 'uuid' || kayan.fields[key]?.target?.fields.id?.kind === 'uuid' ? lowerCase(value) : value]));
+    // A bulk write's own keys are its query; a row's columns are under `data`.
+    return !isObject(input) ? input : bulk ? { ...input, ...(isObject(input.data) && { data: fields(input.data) }) } : fields(input);
+};
 // A symbol: no schema of something a browser can send takes it, so a schema that names
 // the key answers with an issue at the key.
 const probe = Symbol('mithaq.operation.input');
@@ -50,13 +60,21 @@ singleUpdate, cap, read, kayans, of, audit, admin, authorize, catalog,
 /** True where the runner declares a context, which a served call must then carry. */
 contextDeclared, 
 /** The most rows a served read of many may ask for, and one bulk write may match. */
-{ maxLimit, bulkLimit }, tenant) => {
+{ maxLimit, bulkLimit }, tenant, 
+/** The fields of every kayan that keep a row of this one while they name it. */
+pointers) => {
     // Bound, so a step cannot reach `transaction` or the adapter's own client, and sealed, so no
     // step writes a tenant-owned row outside the active organization.
+    const missing = ['upsert', 'sum'].filter((word) => typeof store[word] !== 'function');
+    if (missing.length)
+        throw new Error(`The store is missing required words: ${missing.join(', ')}.`);
     const writes = tenant.seal({
+        find: store.find.bind(store),
         insert: store.insert.bind(store),
         remove: store.remove.bind(store),
         update: store.update.bind(store),
+        upsert: store.upsert.bind(store),
+        sum: store.sum.bind(store),
     });
     const table = [];
     /** The bulk lists, held for the second pass: each needs a method the first builds. */
@@ -64,8 +82,10 @@ contextDeclared,
     // Options come from the plug alone, so nothing a client sends reaches a step as one.
     // On a runner that declares a context, a plug carrying none is refused before any step.
     const publish = (name, effect, input, method, bounded = false) => {
+        const bulk = kayan.operations[name].steps.some((step) => bulkSeals.includes(sealOf(step)));
         // The declared arity is what this widens across, which TypeScript asks two steps for.
-        const called = method;
+        const normalized = ((given, options) => method(lowerUuids({ kayan, input: given, bulk }), options));
+        const called = normalized;
         table.push({
             kayan: kayan.name,
             name,
@@ -74,7 +94,7 @@ contextDeclared,
             input,
             call: (given, { actor, context, draft, autosave, tenant }) => {
                 if (contextDeclared && !context) {
-                    throw new Error(`Kayan "${kayan.name}" operation "${name}" was served with no context, and this build's runner declares one. Give every http plug a context function: fetchHttp({ context }) or orpcHttp({ context }).`);
+                    throw new Error(`Kayan "${kayan.name}" operation "${name}" was served with no context, and this build's runner declares one. Give every http plug a context function: fetchHttp({ context, maxBodyBytes: defaultMaxBodyBytes, onError: console.error }), or orpcHttp with the same options.`);
                 }
                 if (bounded && given && typeof given === 'object' && 'limit' in given) {
                     const limit = given.limit;
@@ -85,7 +105,7 @@ contextDeclared,
                 return called(given, { actor, ...(context ? { context } : {}), ...(draft ? { draft } : {}), ...(autosave ? { autosave } : {}), ...(tenant !== undefined ? { tenant } : {}) });
             },
         });
-        return method;
+        return normalized;
     };
     const methods = Object.create(null);
     for (const [operation, declaration] of Object.entries(kayan.operations)) {
@@ -145,16 +165,20 @@ contextDeclared,
             enumerable: true,
             get: () => kayans(declaration.effect),
         });
+        if (declaration.each && !bulkSeals.includes(kind))
+            throw new Error(`Kayan "${kayan.name}" operation "${operation}" names "each", and only a bulk operation runs another on each row.`);
         // Built in the second pass, where every single-row write it delegates to exists.
         if (bulkSeals.includes(kind)) {
             bulkLists.push({ operation, declaration, tools, input });
             continue;
         }
-        const run = write({ kayan, declaration, tools, store, cap, authorize, admin, tenantOf: tenant.active });
+        const run = write({ kayan, declaration, tools, store, cap, authorize, admin, tenantOf: tenant.active, pointers });
         methods[operation] = publish(operation, declaration.effect, input, run);
     }
     for (const { operation, declaration, tools, input } of bulkLists) {
-        const single = declaration.effect === 'update' ? 'update' : 'delete';
+        const single = declaration.each ?? (declaration.effect === 'update' ? 'update' : 'delete');
+        if (!methods[single])
+            throw new Error(`Kayan "${kayan.name}" operation "${operation}" runs "${single}" on each row it matches, and the kayan has no operation "${single}".`);
         const run = bulk({
             kayan,
             declaration,
@@ -202,7 +226,7 @@ const refuseArkan = (language) => {
 export const buildAsas = (language, { kayan, global, auth, http, messages, statements: declaredStatements, }) => {
     // Refused before any work: core picks no plug of its own.
     if (!http?.length) {
-        throw new Error('buildAsas was handed no "http", and core picks no plug of its own. Name the plugs: http: [fetchHttp()], or http: [orpcHttp(), fetchHttp()] for the typed client.');
+        throw new Error('buildAsas was handed no "http", and core picks no plug of its own. Name the plugs: http: [fetchHttp({ maxBodyBytes: defaultMaxBodyBytes, onError: console.error })], or orpcHttp with the same options first for the typed client.');
     }
     const globals = (global ?? []);
     const globalNames = new Set(globals.map((one) => one.name));
@@ -420,6 +444,20 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
         throw new Error(`Kayan "${betterAuthKayan.join('" and "')}" each carry Better Auth, and kayan "${owned.name}" belongs to the organization a session names. A build with a tenant-owned kayan carries one Better Auth kayan.`);
     }
     const tenant = tenancy({ language, assigned, onError: (error) => auth?.onError?.(error), collection: betterAuthKayan[0] });
+    // A project of one organization that came to hold two would split its people and rows between them
+    // without a word, so it does not start. Two rows are read, not counted, so every store can answer.
+    const refuseExtraTenants = async () => {
+        const target = language.targets.tenant;
+        if (!isTenant(target) || target.organizations === 'many')
+            return;
+        const tenants = resolvedByName.get(target.relationTo);
+        if (!tenants)
+            return;
+        const found = await buildTargets[tenants.store].find({ kayan: tenants.name, args: { limit: 2, page: 1, sort: { field: 'id', direction: 'asc' } } });
+        if (found.docs.length < 2)
+            return;
+        throw new Error(`The tenant target says organizations: '${target.organizations}', and the "${tenants.name}" table holds more than one. Set organizations to 'many' where the project sets it, or merge them into one first; a merge is a migration of the project's own.`);
+    };
     // The tenant scope goes under both authorizers, so replacing either cannot leave it out.
     const authorize = tenant.scoped(service.authorize === defaultAuthorize
         ? defaultAuthorize
@@ -509,12 +547,16 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
             admin,
             authorize,
             openTenant: tenant.open,
+            tenantOf: tenant.active,
             kayans: () => boundKayans('read'),
             of: boundOf('read'),
             audit: service.audit,
             catalog,
+            pickers: Object.fromEntries(resolved.flatMap((other) => Object.values(other.fields)
+                .filter((field) => field.kind !== 'join' && field.target?.name === one.name)
+                .map((field) => [`${other.name}.${field.name}`, field]))),
         });
-        const { methods, table } = operations(one, store, schemas, singleUpdate, cap, read, (effect) => boundKayans(effect === 'read' ? 'read' : 'write'), (effect) => boundOf(effect === 'read' ? 'read' : 'write'), service.audit, admin, authorize, catalog, service.context !== undefined, service, { active: tenant.active, seal: (writes) => tenant.sealWrites({ writes, find: store.find.bind(store), kayanOf: (name) => resolvedByName.get(name) }) });
+        const { methods, table } = operations(one, store, schemas, singleUpdate, cap, read, (effect) => boundKayans(effect === 'read' ? 'read' : 'write'), (effect) => boundOf(effect === 'read' ? 'read' : 'write'), service.audit, admin, authorize, catalog, service.context !== undefined, service, { active: tenant.active, seal: (writes) => tenant.sealWrites({ writes, find: store.find.bind(store), kayanOf: (name) => resolvedByName.get(name) }) }, restrictingPointers(resolved, one));
         operationTable.push(...table);
         const bound = Object.freeze(methods);
         // Only what this kayan's own targets built for it; their configuration stays on `asas.targets`.
@@ -539,7 +581,7 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
                 .filter((operation) => operation.kayan === one.name && operation.effect === effect)
                 .map((operation) => operation.name);
             const operations = {};
-            // Platform staff in the platform app read a tenant-owned kayan across every organization,
+            // Backoffice staff in the backoffice app read a tenant-owned kayan across every organization,
             // so its read is reported as they make it; anyone else is answered in the active one.
             const reach = effect === 'read' && one.tenant && !one.single
                 ? await tenant.open({ actor: actorForAccess, reach: 'all', kayan: one }).catch(() => undefined)
@@ -573,15 +615,24 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
     };
     // Precedence is the order the build lists its kayan: the loop takes the first non-null actor.
     if (authenticating.length && typeof auth?.onError !== 'function') {
-        throw new Error(`buildAsas was handed no "auth.onError", and kayan "${authenticating[0].name}" carries auth. Core reports no failed strategy of its own: name the project's own, such as auth: { onError: console.error }.`);
+        throw new Error(`buildAsas was handed no "auth.onError", and kayan "${authenticating[0].name}" carries auth. Core reports no failed strategy of its own: name the project's own, such as auth: { onError: console.error, maxBodyBytes: defaultMaxBodyBytes }.`);
     }
+    if (authenticating.length)
+        assertMaxBodyBytes('auth', auth.maxBodyBytes);
     const onError = (error) => auth.onError(error);
     const strategies = (() => {
         const list = [];
         // Without this freeze a `roles` function reassigning `v.catalog` would be seen by a
         // `server` factory, and the target and the provider would disagree.
-        const vocabulary = Object.freeze({ catalog: catalog, statements });
         for (const one of authenticating) {
+            const own = resolvedByName.get(one.name);
+            const pointers = restrictingPointers(resolved, own);
+            const ownStore = buildTargets[own.store];
+            const vocabulary = Object.freeze({
+                catalog: catalog,
+                statements,
+                referenced: async (id) => [...(await referencingIds({ id, pointers, store: ownStore })).values()].reduce((sum, ids) => sum + ids.size, 0),
+            });
             const declaration = one.auth;
             if (!isAuthDeclaration(declaration)) {
                 list.push(declaration);
@@ -672,7 +723,7 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
         statements: statements,
         /** Every built operation, flat. Its `procedures` view is a type, keyed by kayan then operation. */
         operations: operationTable,
-        /** The router the first plug built, which a typed client is built from; `undefined` for `fetchHttp()`. */
+        /** The router the first plug built, which a typed client is built from; `undefined` for `fetchHttp`. */
         router: plugs[0]?.router,
         /** Every target as the language passed it, so `asas.targets.drizzle.db` is drizzle. A screen also carries its projection under `client`. */
         targets: Object.fromEntries(Object.entries(buildTargets).map(([name, target]) => [name, isScreen(target) ? { ...target, client: screens[name] } : target])),
@@ -697,15 +748,9 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
                     // logged by the provider as its own 500.
                     if (!request.body)
                         return strategy.handler(request);
-                    let body;
-                    try {
-                        body = await request.arrayBuffer();
-                    }
-                    catch (thrown) {
-                        if (request.signal.aborted)
-                            return new Response(null, { status: 499 });
-                        throw thrown;
-                    }
+                    const body = await boundedBody(request, auth.maxBodyBytes);
+                    if (body instanceof Response)
+                        return body;
                     return strategy.handler(new Request(request.url, { method: request.method, headers: request.headers, body, signal: request.signal }));
                 }
             }
@@ -735,6 +780,8 @@ export const buildAsas = (language, { kayan, global, auth, http, messages, state
             // `readOnly` writes nothing: no push.
             for (const [, store] of stores)
                 await store.connect({ readOnly });
+            if (!readOnly)
+                await refuseExtraTenants();
         },
         destroy: async () => {
             for (const [, store] of stores)

package/dist/asas/cli/mithaq.js

@@ -10,13 +10,36 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // Each generator is imported when its word is asked for, so `better-auth/db` loads
 // only for `generate auth` and the `generate --check` sweep.
 import { realpathSync } from 'node:fs';
+import * as modules from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { Refusal } from '../../mithaq/refusal.js';
-const verbs = ['generate', 'lock', 'migrate', 'screens', 'upgrade'];
+const verbs = ['eject', 'generate', 'lock', 'migrate', 'screens', 'upgrade'];
 const nouns = ['auth', 'messages', 'screens'];
-const usage = 'Usage: mithaq generate auth [--check] | mithaq generate messages [--check] [--no-data-scan] | mithaq generate screens [--check] | mithaq generate --check | mithaq lock [--check] | mithaq migrate [--check] [--name <slug>] | mithaq screens | mithaq upgrade --check | mithaq <target> <command> [--check]';
+const usage = 'Usage: mithaq generate auth [--check] | mithaq generate messages [--check] [--no-data-scan] | mithaq generate screens [--check] | mithaq generate --check | mithaq lock [--check] | mithaq migrate [--check] [--name <slug>] | mithaq screens | mithaq upgrade --check | mithaq eject <item> | mithaq eject --prune | mithaq <target> <command> [--check]';
 // Run as a command, not imported. The bin is a symlink, so compare real paths.
 if (process.argv[1] && realpathSync(process.argv[1]) === import.meta.filename) {
+    // A project's sources may import each other with no extension, as Vite, Bun and drizzle-kit
+    // resolve them and Node does not, so a relative import that names no file is tried as `.ts`,
+    // then as a folder's `index.ts`. Only after Node's own resolution failed, never under node_modules.
+    modules.registerHooks?.({
+        resolve: (specifier, context, next) => {
+            try {
+                return next(specifier, context);
+            }
+            catch (error) {
+                const code = error.code;
+                if (!/^\.\.?\//.test(specifier) || context.parentURL?.includes('/node_modules/') || (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'ERR_UNSUPPORTED_DIR_IMPORT'))
+                    throw error;
+                for (const tail of ['.ts', '/index.ts']) {
+                    try {
+                        return next(`${specifier}${tail}`, context);
+                    }
+                    catch { }
+                }
+                throw error;
+            }
+        },
+    });
     try {
         const [, , verb, noun, ...rest] = process.argv;
         // Before anything reads the project: outside one there is no `src/asas.ts` to import.
@@ -31,7 +54,10 @@ if (process.argv[1] && realpathSync(process.argv[1]) === import.meta.filename) {
         // and never a second word; a target named `migrate` is reached by no spelling.
         const misplaced = (verb === 'migrate' || verb === 'upgrade') && noun !== undefined && !noun.startsWith('--');
         const unchecked = verb === 'upgrade' && !flags.includes('--check');
-        if (verb === undefined || misplaced || unchecked || (verb === 'generate' && !(sweeping || nouns.includes(noun ?? '')))) {
+        // `eject` takes one item or `--prune`, never both and never neither.
+        const ejecting = noun !== undefined && !noun.startsWith('--');
+        const unejected = verb === 'eject' && (ejecting ? flags.length > 0 : flags.join(' ') !== '--prune');
+        if (verb === undefined || misplaced || unchecked || unejected || (verb === 'generate' && !(sweeping || nouns.includes(noun ?? '')))) {
             console.error(usage);
             process.exit(1);
         }
@@ -88,6 +114,12 @@ if (process.argv[1] && realpathSync(process.argv[1]) === import.meta.filename) {
             if (code)
                 process.exit(code);
         }
+        else if (verb === 'eject') {
+            const { eject, prune } = await import('./upgrade.js');
+            const code = ejecting ? await eject(project, noun) : await prune(project);
+            if (code)
+                process.exit(code);
+        }
         else if (verb === 'upgrade') {
             const code = await upgrade();
             if (code)

package/dist/asas/cli/upgrade.d.ts

@@ -1,20 +1,33 @@
-/** The hash of a file as `shadcn add` writes it, without its marker. */
+/** The hash of a copy `shadcn add` made, without its marker and the leading comments it dropped. */
 export declare const hashOf: (text: string) => string;
-/** Appends the marker to every file of every item `shadcn build` wrote into `built`, the registry's `r/`. */
-export declare const mark: (built: URL) => Promise<void>;
+/** A held file's state against the package's text of it, read as `upgrade --check` reads it. */
+export declare const stateOf: (text: string, source: string) => 'up to date' | 'up to date, edited' | 'differs' | 'differs, edited' | 'unknown';
 export type Copied = {
-    /** The file, relative to the project, or the target or item name that resolved outside it. */
+    /** The file, relative to the project, or the target or package path that resolved outside it. */
     path: string;
     state: 'up to date' | 'up to date, edited' | 'differs' | 'differs, edited' | 'unknown' | 'outside' | 'removed';
-    /** The commit the copy's marker names, when it carries one. */
+    /** The version or commit the file's marker names, when it carries one. */
     from?: string;
-    /** The commit the installed registry was built at. */
+    /** The installed mithaq-admin's version. */
     to?: string;
+    /** The item of a file the project always holds, which it never deletes: it ejects the item again instead. */
+    item?: string;
 };
 /**
- * Every registry file the project holds where `shadcn add` writes it, with its state. Reads only;
- * a path that climbs out of the project or the registry is listed as outside, never followed.
+ * Every package file the project holds at its target, ejected or always the project's, with its state. Reads only;
+ * a path that climbs out of the project or the package is listed as outside, never followed.
  */
 export declare const upgradeCheck: (project: URL) => Promise<Copied[] | undefined>;
-/** `mithaq upgrade --check`: one line per copied file, and 1 where any differs. It never writes. */
+/** `mithaq upgrade --check`: one line per file the project holds, and 1 where any differs. It never writes. */
 export declare const run: (project: URL) => Promise<number>;
+/**
+ * `mithaq eject <item>`: writes the item's own files where the project keeps them, each byte for byte with a marker,
+ * and never over a file already there. It copies no other item and installs nothing: the package serves every
+ * sibling, so it only names a primitive or an npm package the project lacks.
+ */
+export declare const eject: (project: URL, name: string) => Promise<number>;
+/**
+ * `mithaq eject --prune`: deletes every marked file in the folders pieces are ejected into whose text still hashes
+ * to its marker, so the package draws it again. Never an edited, unmarked or `~/` file.
+ */
+export declare const prune: (project: URL) => Promise<number>;