@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/rbac/index.js

@@ -0,0 +1,182 @@
+import { rowsOf } from '../mithaq/rows.js';
+import { writeSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { actorPermissions, markAuthActor } from '../asas/actor.js';
+import { Refusal } from '../mithaq/refusal.js';
+import { isService, isStore } from '../mithaq/language.js';
+import { resolvedKayans } from '../mithaq/types.js';
+/**
+ * The keys an actor holds for a kayan: what the build's access target resolved,
+ * or the kayan's own rows where no target answered. Precedence, never a union.
+ */
+export const heldPermissions = ({ access, user }) => actorPermissions(user) ?? rowsOf(access)?.permissions(user);
+/** One page of every row a filter matches, which is how each table is read. */
+export const allRows = async ({ store, kayan, where }) => store.find({ kayan, args: { limit: 0, page: 1, sort: { field: 'id', direction: 'asc' }, where } });
+/** A tenant a row can be filtered by. Nothing else scopes a read, so nothing else reads. */
+export const scoped = (value) => typeof value === 'string' || typeof value === 'number';
+// A read that throws is caught at `resolveAssigned`, so a store that is down
+// makes an actor that holds nothing rather than one that is not signed in.
+export const assignedSlugs = async ({ store, kayan, field, tenant, member }) => {
+    // An assignment read without a tenant, or of a kayan no tenant owns, would be every tenant's.
+    if (!field || !scoped(tenant) || !scoped(member))
+        return [];
+    const found = await allRows({ store, kayan, where: {
+            and: [{ [field]: { equals: tenant } }, { user: { equals: member } }],
+        } });
+    const names = found.docs.map((row) => row.role);
+    return [...new Set(names.filter((one) => typeof one === 'string' && one !== ''))];
+};
+/**
+ * A role slug that is one of the project's own, whose keys are code. The rest
+ * are rows, and a target reads them from wherever it holds them.
+ */
+export const systemKeys = (roles, slugs) => {
+    const keys = new Set();
+    const custom = [];
+    let everything = false;
+    for (const slug of slugs) {
+        // An own key only: a slug is a column a caller wrote.
+        const role = Object.hasOwn(roles, slug) ? roles[slug] : undefined;
+        if (!role) {
+            custom.push(slug);
+            continue;
+        }
+        if (role.permissions === '*')
+            everything = true;
+        else
+            for (const key of role.permissions)
+                keys.add(key);
+    }
+    return { custom, everything, keys };
+};
+// Never re-export this from a package entry: it marks a copy of any actor and
+// slugs as trusted, so a caller outside core could mint the snapshot every reader trusts.
+export const heldSlugs = ({ roles, rolesOf, slugs, actor }) => {
+    if (!rolesOf)
+        return slugs;
+    if (!actor)
+        return [];
+    const answered = rolesOf(markAuthActor({ ...actor, roles: slugs }));
+    if (!Array.isArray(answered))
+        return [];
+    const kept = answered.filter((one) => typeof one === 'string' && (slugs.includes(one) || Object.hasOwn(roles, one)));
+    return [...new Set(kept)];
+};
+/** The access target whose custom roles are rows of a kayan the project ships, beside its system roles in code. */
+export const rbacTarget = ({ roles, rolesOf, access, kayan, }) => {
+    // Both targets come through here, so the one refusal covers both.
+    for (const key of ['roles', 'memberRoles']) {
+        if (typeof kayan?.[key] !== 'string') {
+            throw new Error(`The access target names no kayan.${key}. Pass kayan: { roles, memberRoles }, the names of the kayan holding the custom roles and the assignments.`);
+        }
+    }
+    const { roles: roleKayan, memberRoles } = kayan;
+    return {
+        capability: 'access',
+        type: 'rbac',
+        roles,
+        ...(rolesOf ? { rolesOf } : {}),
+        access: (access ?? {}),
+        reads: [roleKayan, memberRoles],
+        commands: {
+            assign: async ({ asas, flags }) => {
+                // A sweep reaches this after `generate messages --check` destroyed the shared pool.
+                if (flags.includes('--check')) {
+                    console.log('mithaq rbac assign --check writes nothing.');
+                    return 0;
+                }
+                try {
+                    const values = {};
+                    for (let index = 0; index < flags.length; index += 2) {
+                        const flag = flags[index];
+                        const value = flags[index + 1];
+                        if (!flag || !['--tenant', '--user', '--role'].includes(flag) || !value || value.startsWith('--') || values[flag]) {
+                            throw new Refusal('mithaq rbac assign requires one value each for --tenant, --user and --role.');
+                        }
+                        values[flag] = value;
+                    }
+                    for (const flag of ['--tenant', '--user', '--role']) {
+                        if (!values[flag])
+                            throw new Refusal(`Missing ${flag} for mithaq rbac assign.`);
+                    }
+                    const tenant = values['--tenant'];
+                    const user = values['--user'];
+                    const role = values['--role'];
+                    if (!Object.hasOwn(roles, role))
+                        throw new Refusal(`Role "${role}" is not declared on the access target.`);
+                    if (role === 'super_admin')
+                        throw new Refusal('Role "super_admin" is the platform role and cannot be assigned in a tenant.');
+                    const project = asas;
+                    const declarations = resolvedKayans.get(project) ?? {};
+                    const assignment = declarations[memberRoles];
+                    if (!assignment)
+                        throw new Refusal(`mithaq rbac assign requires the "${memberRoles}" kayan in this build.`);
+                    const owner = assignment.tenant;
+                    if (!owner)
+                        throw new Refusal(`mithaq rbac assign writes an assignment of one tenant, and kayan "${memberRoles}" places no field bound to the tenant target.`);
+                    // This kayan may use a different store from the service target's default.
+                    const store = project.targets[assignment.store];
+                    if (!isStore(store))
+                        throw new Refusal(`Kayan "${memberRoles}" names no store for mithaq rbac assign.`);
+                    const membership = declarations.member;
+                    if (!membership)
+                        throw new Refusal('mithaq rbac assign requires the provider "member" kayan in this build.');
+                    // The membership is read inside the assignment's transaction, so both kayan must live in that store.
+                    if (membership.store !== assignment.store) {
+                        throw new Refusal(`mithaq rbac assign reads both kayan in one transaction, but kayan "member" is in store "${membership.store}" and kayan "${memberRoles}" is in store "${assignment.store}".`);
+                    }
+                    const service = Object.values(project.targets).find(isService);
+                    const actor = { command: 'mithaq rbac assign', osUser: userInfo().username };
+                    await store.transaction(async (tx) => {
+                        const member = await store.find({ kayan: 'member', args: {
+                                limit: 1, page: 1, sort: { field: 'id', direction: 'asc' },
+                                where: { and: [{ organizationId: { equals: tenant } }, { userId: { equals: user } }] },
+                            }, tx });
+                        if (!member.docs.length)
+                            throw new Refusal(`User "${user}" is not a provider member of tenant "${tenant}".`);
+                        const existing = await store.find({ kayan: memberRoles, args: {
+                                limit: 1, page: 1, sort: { field: 'id', direction: 'asc' },
+                                where: { and: [{ [owner]: { equals: tenant } }, { user: { equals: user } }, { role: { equals: role } }] },
+                            }, tx });
+                        if (existing.docs.length)
+                            throw new Refusal(`Role "${role}" is already assigned to user "${user}" in tenant "${tenant}".`);
+                        const written = new Date();
+                        const row = await store.insert({ tx, kayan: memberRoles, data: { createdAt: written, role, [owner]: tenant, updatedAt: written, user } });
+                        // The language checked the sink takes a `CommandActor`, which is what the cast names.
+                        if (service?.audit)
+                            await service.audit({ context: Object.freeze({ chain: [`${memberRoles}.assign`], depth: 1, source: 'cli' }), effect: 'create', kayan: assignment, operation: 'assign', dataAfter: row, store, tx, user: actor });
+                    });
+                    writeSync(1, `${JSON.stringify({ actor, tenant, user, role })}\n`);
+                    return 0;
+                }
+                finally {
+                    await asas.destroy();
+                }
+            },
+        },
+        resolve: async ({ store, tenant, member, actor, ownership }) => {
+            const slugs = await assignedSlugs({ store, kayan: memberRoles, field: ownership(memberRoles), tenant, member });
+            const { custom, everything, keys } = systemKeys(roles, heldSlugs({ roles, rolesOf, slugs, actor }));
+            if (everything)
+                return { permissions: '*', roles: slugs };
+            const field = ownership(roleKayan);
+            // A role table no tenant owns holds no tenant's custom role, so it grants nothing.
+            if (custom.length && field && scoped(tenant)) {
+                // Caught here, so a role table that is down loses the keys and not the assignment.
+                const found = await allRows({ store, kayan: roleKayan, where: {
+                        and: [{ [field]: { equals: tenant } }, { name: { in: custom } }],
+                    } }).catch(() => undefined);
+                if (!found)
+                    return { permissions: [], roles: slugs };
+                const held = found.docs.map((row) => row.permissions);
+                // A malformed column voids the whole answer: a subset of a list nothing vouched for is still such a grant.
+                if (!held.every((one) => Array.isArray(one) && one.every((key) => typeof key === 'string'))) {
+                    return { permissions: [], roles: slugs };
+                }
+                for (const key of held.flat())
+                    keys.add(key);
+            }
+            return { permissions: [...keys], roles: slugs };
+        },
+    };
+};

package/dist/rbac/steps.d.ts

@@ -0,0 +1,22 @@
+import type { Ctx, Tools } from '../asas/runner/steps.ts';
+import { type SystemRoles } from './index.ts';
+export declare const keepOperationKeys: (catalog: readonly string[], operationKeys: Readonly<Record<string, string>>) => void;
+export declare const fieldlessOperation: (keys: readonly string[], operationKeys: Readonly<Record<string, string>>) => {
+    key: string;
+    kayan: string;
+} | undefined;
+/**
+ * The validate step a role kayan puts after `validate`: a role row may hold only keys
+ * the catalog names and the granter itself holds.
+ */
+export declare const grantedPermissions: (ctx: Ctx, tools: Tools) => Ctx;
+/**
+ * The validate step a `memberRoles` kayan puts before its store step: an actor may
+ * assign only a role whose keys it already holds.
+ */
+export declare const assignableRole: (roles: SystemRoles, roleKayan: string) => (ctx: Ctx, tools: Tools) => Promise<Ctx>;
+/**
+ * The step after `grantedPermissions` in a role kayan's write lists: a tenant's role
+ * row may not take a system role's name.
+ */
+export declare const writableRoleName: (roles: SystemRoles) => (ctx: Ctx) => Ctx;

package/dist/rbac/steps.js

@@ -0,0 +1,161 @@
+import { denied, invalid } from '../asas/runner/errors.js';
+import { heldPermissions } from './index.js';
+const KEYS = 'permissions';
+// Kept against each build's frozen catalog, which every operation is handed as `tools.catalog`.
+const operationKeysOf = new WeakMap();
+export const keepOperationKeys = (catalog, operationKeys) => {
+    operationKeysOf.set(catalog, operationKeys);
+};
+// A role holding an operation key of a kayan but no field key of it is refused
+// every read of that kayan's fields, so its list draws nothing.
+export const fieldlessOperation = (keys, operationKeys) => {
+    const key = keys.find((one) => Object.hasOwn(operationKeys, one) && !keys.some((other) => other.startsWith(`${operationKeys[one]}.fields.`)));
+    return key === undefined ? undefined : { key, kayan: operationKeys[key] };
+};
+/**
+ * The validate step a role kayan puts after `validate`: a role row may hold only keys
+ * the catalog names and the granter itself holds.
+ */
+export const grantedPermissions = (ctx, tools) => {
+    // A write that names only the name is still a grant: a rename re-targets every key
+    // the row holds at a different set of members. `dataBefore` is what the store holds.
+    const data = ctx.data;
+    const written = data[KEYS] ?? ctx.dataBefore?.[KEYS];
+    // Checked here too, so a list a step wrote is checked as a caller's is, and a
+    // stored column no shape vouched for refuses rather than being read past.
+    if (written === undefined)
+        return ctx;
+    if (!Array.isArray(written) || written.some((key) => typeof key !== 'string')) {
+        throw invalid({
+            message: `A "${ctx.kayan.name}" row's "${KEYS}" must be a list of permission keys.`,
+            key: 'error.invalid.permissions',
+            params: { kayan: ctx.kayan.name, field: KEYS },
+        });
+    }
+    const keys = written;
+    const known = new Set(tools.catalog);
+    for (const key of keys) {
+        if (known.has(key))
+            continue;
+        throw invalid({
+            message: `Permission "${key}" is not a key of this project's catalog. A key is "<kayan>.<operation>", "<kayan>.fields.<field>" or "screen.<screen>".`,
+            key: 'error.invalid.permission',
+            params: { kayan: ctx.kayan.name, permission: key },
+        });
+    }
+    // Asked only of a write that names the column, so an older row can still be renamed and deleted.
+    const fieldless = data[KEYS] !== undefined && fieldlessOperation(keys, operationKeysOf.get(tools.catalog) ?? {});
+    if (fieldless) {
+        throw invalid({
+            message: `A "${ctx.kayan.name}" row holds operation key "${fieldless.key}" of kayan "${fieldless.kayan}" and no "${fieldless.kayan}.fields.<field>" key, so every read of it is refused for its fields. Grant the fields it reads, or drop the operation.`,
+            key: 'error.invalid.permission_fields',
+            params: { kayan: ctx.kayan.name, permission: fieldless.key, resource: fieldless.kayan },
+        });
+    }
+    // Read from the trusted snapshot, never the actor object, so a `permissions`
+    // property a caller wrote on itself buys nothing.
+    const held = heldPermissions({ access: ctx.kayan.access, user: ctx.actor });
+    if (held === true)
+        return ctx;
+    // `undefined` is a granter whose holdings nothing states, not one holding everything:
+    // a row written then would become a live grant the moment a store is turned on.
+    const missing = held === undefined ? keys : keys.filter((key) => !held.has(key));
+    if (!missing.length)
+        return ctx;
+    throw denied({
+        message: `Forbidden: a "${ctx.kayan.name}" row may not grant ${missing.map((key) => `"${key}"`).join(', ')}, which the granter does not hold.`,
+        key: 'error.forbidden.grant',
+        params: { kayan: ctx.kayan.name, permissions: missing },
+    });
+};
+const NAME = 'name';
+const ROLE = 'role';
+// A `permissions` column that is not a list of strings, or a role kayan that was not
+// read, reads as `'*'`: what may be handed over is answered with the largest it could be.
+const roleKeys = async ({ roles, kayan, slug, tools }) => {
+    // An own key only: `constructor` or `__proto__` read through the prototype would be a 500 one line later.
+    const system = Object.hasOwn(roles, slug) ? roles[slug] : undefined;
+    if (system)
+        return system.permissions === '*' ? '*' : system.permissions;
+    // Through the bound registry, so the read runs under this actor, its transaction and its
+    // tenant scope, which keeps a role of another tenant out. Rows of one name in a table no
+    // tenant owns are unioned, which only asks the assigner for more.
+    const bound = tools.kayans?.[kayan];
+    const found = await bound?.find?.({ where: { [NAME]: { equals: slug } } });
+    // Not read is not a role holding nothing: it reads as `'*'`, so a guard that could not look refuses.
+    if (!found)
+        return '*';
+    if (!found.docs.length)
+        return undefined;
+    const keys = [];
+    for (const row of found.docs) {
+        const held = row[KEYS];
+        if (!Array.isArray(held) || held.some((key) => typeof key !== 'string'))
+            return '*';
+        keys.push(...held);
+    }
+    return keys;
+};
+/**
+ * The validate step a `memberRoles` kayan puts before its store step: an actor may
+ * assign only a role whose keys it already holds.
+ */
+export const assignableRole = (roles, roleKayan) => {
+    if (typeof roleKayan !== 'string') {
+        throw new Error('assignableRole(roles, roleKayan) names no roleKayan. Pass the name of the kayan holding the custom roles, the access target\'s kayan.roles.');
+    }
+    return async (ctx, tools) => {
+        // A write that moves the row to another member is still an assignment of the role it names.
+        const data = ctx.data;
+        const slug = data[ROLE] ?? ctx.dataBefore?.[ROLE];
+        if (typeof slug !== 'string' || slug === '')
+            return ctx;
+        // Create and update refuse a missing slug first: even a root granter may not
+        // plant a row that a later role could arm.
+        const keys = await roleKeys({ roles, kayan: roleKayan, slug, tools });
+        if (keys === undefined) {
+            if (tools.kind === 'remove')
+                return ctx;
+            throw invalid({
+                message: `Role "${slug}" is not declared in the system roles or the "${roleKayan}" role table of this tenant.`,
+                key: 'error.invalid.role',
+                params: { kayan: ctx.kayan.name, role: slug },
+            });
+        }
+        // Read from the trusted snapshot, never the actor object.
+        const held = heldPermissions({ access: ctx.kayan.access, user: ctx.actor });
+        if (held === true)
+            return ctx;
+        if (keys === '*') {
+            throw denied({
+                message: `Forbidden: a "${ctx.kayan.name}" row may not assign role "${slug}", which holds every key of this project, and the assigner does not.`,
+                key: 'error.forbidden.assign',
+                params: { kayan: ctx.kayan.name, permissions: ['*'], role: slug },
+            });
+        }
+        // Refused for the reason `grantedPermissions` refuses an `undefined` holding.
+        const missing = held === undefined ? keys : keys.filter((key) => !held.has(key));
+        if (!missing.length)
+            return ctx;
+        throw denied({
+            message: `Forbidden: a "${ctx.kayan.name}" row may not assign role "${slug}", which holds ${missing.map((key) => `"${key}"`).join(', ')}, which the assigner does not hold.`,
+            key: 'error.forbidden.assign',
+            params: { kayan: ctx.kayan.name, permissions: missing, role: slug },
+        });
+    };
+};
+/**
+ * The step after `grantedPermissions` in a role kayan's write lists: a tenant's role
+ * row may not take a system role's name.
+ */
+export const writableRoleName = (roles) => (ctx) => {
+    const data = ctx.data;
+    const name = data[NAME] ?? ctx.dataBefore?.[NAME];
+    if (typeof name !== 'string' || !Object.hasOwn(roles, name))
+        return ctx;
+    throw invalid({
+        message: `A "${ctx.kayan.name}" row may not be named "${name}", which is a role this project ships: its keys are code, and a row of the same name would grant nothing and list beside it as though it did.`,
+        key: 'error.invalid.system_role_name',
+        params: { kayan: ctx.kayan.name, role: name },
+    });
+};

package/dist/rich-text/index.d.ts

@@ -0,0 +1,27 @@
+import type { Klass, LexicalNode } from 'lexical';
+import { z } from 'zod';
+import type { StandardSchemaV1 } from '../mithaq/standard-schema.ts';
+import type { ResolvedField } from '../mithaq/types.ts';
+import { type RichTextValue } from './rich-text.ts';
+/**
+ * The rukn a project lays down for rich text, over its own node list:
+ * `arkan: [base, richText({ nodes: richTextNodes })]`.
+ */
+export declare const richText: ({ nodes }: {
+    nodes: readonly Klass<LexicalNode>[];
+}) => {
+    readonly name: "richText";
+    readonly kinds: {
+        richText: import("../base/kinds.ts").Kind<RichTextValue, "providedBy" | "required"> & {
+            targets: {
+                readonly drizzle: (field: ResolvedField) => import("drizzle-orm/pg-core").PgJsonbBuilder;
+                readonly zod: (field?: ResolvedField) => z.ZodCustom<RichTextValue, RichTextValue>;
+                readonly standardSchema: (field: ResolvedField) => StandardSchemaV1<unknown, RichTextValue>;
+                readonly screen: {
+                    readonly control: "richText";
+                    readonly cell: "richText";
+                };
+            };
+        };
+    };
+};

package/dist/rich-text/index.js

@@ -0,0 +1,58 @@
+import { jsonb } from 'drizzle-orm/pg-core';
+import { z } from 'zod';
+import { kind } from '../base/kinds.js';
+import { defineRukn } from '../mithaq/rukn.js';
+import { isRichText, richTextReader, storedRichText } from './rich-text.js';
+// An emptied editor still sends a root and one empty paragraph, so a blank text
+// with no decorator is missing for `required`.
+const refusalOf = ({ field, read, value }) => {
+    const key = (rule) => (field?.kayan ? `${field.kayan}.${field.name}.${rule}` : undefined);
+    const required = { message: key('required') ?? 'Required' };
+    if (value === undefined && field?.rules?.required)
+        return required;
+    const got = read(value);
+    if ('refused' in got)
+        return { message: key('invalid') ?? got.refused, ...(got.type && { params: { type: got.type } }) };
+    if (field?.rules?.required && read !== storedRichText && got.text.trim() === '' && !got.holdsDecorator)
+        return required;
+    return undefined;
+};
+const readerOf = ({ field, nodes }) => field?.richText ?? richTextReader(nodes, field?.filesIn);
+const richTextKind = ({ nodes }) => kind(isRichText)({
+    label: { en: 'Rich text', ar: 'نص منسق' },
+    message: { en: 'This is not rich text.', ar: 'هذا ليس نصا منسقا.' },
+    rules: ['providedBy', 'required'],
+    // The value is a tree, so the store searches its text and no other operator or order applies.
+    operators: ['like', 'contains', 'exists'],
+    sortable: false,
+    targets: {
+        drizzle: (field) => jsonb(field.column),
+        zod: (field) => {
+            const read = readerOf({ field, nodes });
+            return z.custom().superRefine((value, ctx) => {
+                const refused = refusalOf({ field, read, value });
+                if (refused)
+                    ctx.addIssue({ code: 'custom', ...refused });
+            });
+        },
+        standardSchema: (field) => {
+            const read = readerOf({ field, nodes });
+            return {
+                '~standard': {
+                    version: 1,
+                    vendor: 'mithaq',
+                    validate: (value) => {
+                        const refused = refusalOf({ field, read, value });
+                        return refused ? { issues: [refused] } : { value: value };
+                    },
+                },
+            };
+        },
+        screen: { control: 'richText', cell: 'richText' },
+    },
+});
+/**
+ * The rukn a project lays down for rich text, over its own node list:
+ * `arkan: [base, richText({ nodes: richTextNodes })]`.
+ */
+export const richText = ({ nodes }) => defineRukn({ name: 'richText', kinds: { richText: richTextKind({ nodes }) } });

package/dist/rich-text/rich-text.d.ts

@@ -0,0 +1,159 @@
+import { DecoratorNode, type ElementFormatType, type Klass, type LexicalNode, type LexicalUpdateJSON, type SerializedLexicalNode } from 'lexical';
+/** One node of Lexical's serialized editor state: a `type`, and `children` where it holds any. */
+export type RichTextNode = {
+    type: string;
+    children?: RichTextNode[];
+    text?: string;
+    [key: string]: unknown;
+};
+/** What a `richText` field holds: Lexical's `editorState.toJSON()`, a root of `type: 'root'`. */
+export type RichTextValue = {
+    root: RichTextNode & {
+        type: 'root';
+        children: RichTextNode[];
+    };
+    [key: string]: unknown;
+};
+/**
+ * How deep a rich text value may nest, how large it may be and how many nodes it may hold,
+ * all checked before any Lexical code reads it.
+ */
+export declare const richTextBounds: {
+    depth: number;
+    bytes: number;
+    nodes: number;
+};
+/** Whether a link may point here: `http`, `https`, `mailto`, `tel`, a fragment or a path. */
+export declare const safeUrl: (url: unknown) => boolean;
+/**
+ * Why a value is no Lexical editor state a `richText` column may hold, or nothing. Runs before
+ * any Lexical code reads the value; a `style` is refused, since no editor of the project writes one.
+ */
+export declare const richTextGuard: (value: unknown) => string | undefined;
+/** Whether a value passes `richTextGuard`, which is all the kind itself asks of one. */
+export declare const isRichText: (value: unknown) => value is RichTextValue;
+/** The node classes the registry's editor draws. A project's list spreads it: `[...defaultNodes, CalloutNode]`. */
+export declare const defaultNodes: readonly Klass<LexicalNode>[];
+/** Every node type a list of classes can read, the core ones included. */
+export declare const typesOf: (nodes: readonly Klass<LexicalNode>[]) => ReadonlySet<string>;
+/**
+ * The first node type under a value's `root` that `types` does not hold, or nothing, and `''`
+ * past the depth bound. Read off the JSON, since a production Lexical minifies its errors.
+ */
+export declare const unknownType: ({ node, types, depth }: {
+    node: unknown;
+    types: ReadonlySet<string>;
+    depth?: number;
+}) => string | undefined;
+/** An upload node as Payload's lexical editor writes it, v3. */
+export type SerializedUploadNode = SerializedLexicalNode & {
+    type: 'upload';
+    version: 3;
+    format: ElementFormatType;
+    id: string;
+    relationTo: string;
+    value: string;
+    fields: Record<string, unknown> | null;
+};
+/**
+ * A file inside rich text, in the JSON Payload's editor writes (`type: 'upload'`, `version: 3`).
+ * DOM-free, so the server checks a write with it. A project opts in: `[...defaultNodes, UploadNode]`.
+ */
+export declare class UploadNode extends DecoratorNode<unknown> {
+    $config(): import("lexical").BaseStaticNodeConfig & {
+        readonly upload?: {
+            readonly extends: typeof DecoratorNode;
+            readonly stateConfigs: readonly [{
+                readonly stateConfig: import("lexical").StateConfig<"format", ElementFormatType>;
+                readonly flat: true;
+            }, {
+                readonly stateConfig: import("lexical").StateConfig<"id", string>;
+                readonly flat: true;
+            }, {
+                readonly stateConfig: import("lexical").StateConfig<"relationTo", string>;
+                readonly flat: true;
+            }, {
+                readonly stateConfig: import("lexical").StateConfig<"value", string>;
+                readonly flat: true;
+            }, {
+                readonly stateConfig: import("lexical").StateConfig<"fields", Record<string, unknown> | null>;
+                readonly flat: true;
+            }];
+        } | undefined;
+    } & import("lexical").StaticNodeTypeAccessor<"upload"> & import("lexical").StaticNodeConfigAccessor<{
+        readonly extends: typeof DecoratorNode;
+        readonly stateConfigs: readonly [{
+            readonly stateConfig: import("lexical").StateConfig<"format", ElementFormatType>;
+            readonly flat: true;
+        }, {
+            readonly stateConfig: import("lexical").StateConfig<"id", string>;
+            readonly flat: true;
+        }, {
+            readonly stateConfig: import("lexical").StateConfig<"relationTo", string>;
+            readonly flat: true;
+        }, {
+            readonly stateConfig: import("lexical").StateConfig<"value", string>;
+            readonly flat: true;
+        }, {
+            readonly stateConfig: import("lexical").StateConfig<"fields", Record<string, unknown> | null>;
+            readonly flat: true;
+        }];
+    }>;
+    /** Refused where either half of what the node points at is missing, which an absent key leaves at its default. */
+    updateFromJSON(json: LexicalUpdateJSON<SerializedLexicalNode>): this;
+    /** Every key, defaults included, as Payload's editor writes it. */
+    exportJSON(): SerializedUploadNode;
+    getRelationTo(): string;
+    getValue(): string;
+    getFormat(): ElementFormatType;
+    /** Points the node at one file, with a fresh node id: an ObjectID's twelve bytes in hex. */
+    setUpload(relationTo: string, value: string): this;
+    createDOM(): HTMLElement;
+    updateDOM(): false;
+    isInline(): false;
+    decorate(): unknown;
+}
+/** What a write's value reads as: its text and whether it holds a decorator, or why it is refused. */
+export type RichTextRead = {
+    text: string;
+    holdsDecorator?: boolean;
+} | {
+    refused: string;
+    type?: string;
+};
+/**
+ * A reader of `richText` values over a node list: the guard walk, then a headless parse.
+ * `uploads` names the kayan an `UploadNode` may point at.
+ */
+export declare const richTextReader: (nodes: readonly Klass<LexicalNode>[], uploads?: readonly string[]) => (value: unknown) => RichTextRead;
+/**
+ * How a stored `richText` value is read back: a root with children and nothing more,
+ * so a value holding a node the project has since dropped still reads.
+ */
+export declare const storedRichText: (value: unknown) => RichTextRead;
+/** What a converter left out of a value: the node's path in what it was handed, its type, and why. */
+export type RichTextDropped = {
+    path: string;
+    type: string;
+    reason: string;
+};
+/** A converted value, which the guard and the parse of the same node list take, with what was left out of it, or why there is none. */
+export type RichTextConverted = {
+    value: RichTextValue;
+    dropped: RichTextDropped[];
+} | {
+    refused: string;
+};
+/**
+ * A value Payload's lexical editor stored, as one this editor reads, with what could not come across.
+ * A link the editor would not write is replaced by its text; a `style` is cleared.
+ */
+export declare const convertPayloadToLexical: ({ data, nodes }: {
+    data: unknown;
+    nodes: readonly Klass<LexicalNode>[];
+}) => RichTextConverted;
+/** Plain text as a value: a blank line starts a paragraph, a newline is a `linebreak` and a tab a `tab`. */
+export declare const convertPlaintextToLexical: ({ text, nodes }: {
+    text: string;
+    nodes: readonly Klass<LexicalNode>[];
+}) => RichTextConverted;