@adminiumjs/manifest 0.3.39 → 0.3.41

package/dist/public-access.js

@@ -31,12 +31,29 @@ import { publicConsentSchema } from './people.js';
 import { kindOf, rulesOf } from './capacity.js';
 import { formulaColumns } from './formula.js';
 import { refSchema, scalarSchema, settingRefSchema, valueFits, } from './refs.js';
+import { FORMS_BECAME_TABLE_MAX } from './forms.js';
 import { momentIssues, momentOffsetSchema, plainMomentSchema, wallTimeSchema } from './refs.js';
 import { conditionIssues, linkedConditionSchema, reachedOnlyByUndo, stateConditionSchema } from './states.js';
 /** The fewest characters (its prefix apart) of a code that opens its own row (`unlockBy.self`). */
 export const SELF_UNLOCK_MIN_LENGTH = 10;
 /** The key every entry uses unless it names another. */
 export const CUSTOMER_KEY = 'customer';
+/**
+ * The reserved key name of the entries that open a table to FORMS: an answer
+ * to a form may become a new row of the table, through this entry's
+ * `writable` columns, `defaults` and `anonymous` limits. No browser key of
+ * this name is ever made, and the public API never serves such an entry: it
+ * is read by the forms door alone, so opening a table to forms does not open
+ * it to the public API.
+ */
+export const FORMS_KEY = 'forms';
+/**
+ * What a forms entry may say. A form only ever creates a row (it never reads
+ * one back, changes one or signs anyone in), so every word about reading,
+ * claims, sessions, children, files and the entry's own confirmation mail is
+ * left out: forms send their own.
+ */
+export const FORMS_ENTRY_WORDS = ['table', 'methods', 'key', 'writable', 'writableValues', 'defaults', 'requires', 'agrees', 'anonymous', 'requireSetting', 'module', 'source'];
 /** The longest a plain-text value may be unless its column says longer: a name. */
 export const PLAIN_TEXT_MAX = 80;
 /** The most digits a plain-text column may take in all: "table 12", "2 without onions", never a phone number. */
@@ -592,6 +609,13 @@ export const publicAccessSchema = z
         .optional(),
     /** Which browser key serves the entry: `customer`, or one of `publicKeys`. */
     key: keyNameSchema.optional(),
+    /**
+     * A forms entry only: the one `writable` text column a form's fixed
+     * "Source" value goes into (an enquiry's "From form": the form's name, or
+     * what the owner words it). The builder shows that row on this column;
+     * the answer door writes it as the form's settings say, like any other.
+     */
+    source: refSchema.optional(),
     /** The part of the app the entry belongs to: closed while it is off (see `modules.ts`). */
     module: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, 'a module id is kebab-case').optional(),
     /**
@@ -699,6 +723,9 @@ export const publicKeysSchema = z
     .record(keyNameSchema, publicKeySchema)
     .refine((keys) => !(CUSTOMER_KEY in keys) || Object.keys(keys[CUSTOMER_KEY] ?? {}).every((field) => field === 'peak'), {
     message: '"customer" is the app\'s own key: only its peak is said here',
+})
+    .refine((keys) => !(FORMS_KEY in keys), {
+    message: '"forms" is the name of the entries forms write through, and no browser key: name the key otherwise',
 });
 /**
  * The own links of the rows a person of `identityTable` holds: each table a
@@ -765,6 +792,65 @@ export function resendAddressOf(outbox, kind, table, columnsOf) {
         return null;
     return { columns, ...(person === undefined ? {} : { person }) };
 }
+/** Whether anyone at all may read rows through an entry: no claim, no session, no person, no parent row it is read with. */
+function readByAnyone(entry) {
+    return (entry.methods.includes('GET') &&
+        entry.kind !== 'availability' &&
+        entry.claim === undefined &&
+        entry.claimedBy === undefined &&
+        entry.identity === undefined &&
+        entry.visibleWith === undefined &&
+        entry.level === undefined);
+}
+/**
+ * A forms entry's own rules: it creates (POST) and nothing else, under the
+ * anonymous limits every stranger's create has, with the columns a form may
+ * fill named; one per table; and no entry on any key lets anyone read the
+ * rows strangers add through it.
+ */
+function formsEntryIssues(entry, i, entries, appKey, index) {
+    const out = [];
+    const at = (...rest) => ['publicAccess', i, ...rest];
+    // Each answer keeps the row it became by its table's stored name: it must fit an answers table, whole.
+    const stored = appKey === undefined ? 0 : appKey.length + 1 + entry.table.length;
+    if (stored > FORMS_BECAME_TABLE_MAX) {
+        out.push({ path: at('table'), message: `a form's answer names the row it became by "<app>:<table>", at most ${String(FORMS_BECAME_TABLE_MAX)} characters: "${appKey ?? ''}:${entry.table}" is ${String(stored)}` });
+    }
+    const allowed = FORMS_ENTRY_WORDS;
+    for (const word of Object.keys(entry)) {
+        if (!allowed.includes(word))
+            out.push({ path: at(word), message: `a forms entry only lets a form add a row: "${word}" is not said on it` });
+    }
+    if (entry.methods.length !== 1 || entry.methods[0] !== 'POST')
+        out.push({ path: at('methods'), message: 'a forms entry adds a row and does nothing else: its methods are ["POST"]' });
+    if (entry.anonymous === undefined)
+        out.push({ path: at('anonymous'), message: 'a form is sent by strangers: a forms entry says its anonymous limits' });
+    if ((entry.writable ?? []).length === 0)
+        out.push({ path: at('writable'), message: 'a forms entry names the columns a form may fill (writable)' });
+    if (entry.source !== undefined) {
+        const named = index.column(entry.table, entry.source);
+        if (!(entry.writable ?? []).includes(entry.source)) {
+            out.push({ path: at('source'), message: `a form's source goes into one of the columns a form may fill: put "${entry.source}" in writable` });
+        }
+        else if (named !== undefined && (named.type === 'fk' || named.references !== undefined)) {
+            out.push({ path: at('source'), message: `"${entry.source}" links to another row: a form's source is words, so it goes into a text column` });
+        }
+        else if (named !== undefined && named.type !== 'text') {
+            out.push({ path: at('source'), message: `"${entry.source}" holds ${named.type}: a form's source is words, so it goes into a text column` });
+        }
+    }
+    if (entries.findIndex((other) => other.key === FORMS_KEY && other.table === entry.table) !== i) {
+        out.push({ path: at('table'), message: `"${entry.table}" is opened to forms by another entry already: one forms entry per table` });
+    }
+    const reader = entries.findIndex((other) => other !== entry && other.table === entry.table && readByAnyone(other));
+    if (reader !== -1) {
+        out.push({
+            path: at('table'),
+            message: `strangers add rows to "${entry.table}" through forms, and entry ${String(reader)} lets anyone read its rows: everyone could read what people typed into a form`,
+        });
+    }
+    return out;
+}
 /** Everything in `publicAccess` and `publicKeys` that names something undeclared, or breaks a rule. */
 export function publicAccessIssues(entries, ctx) {
     const out = [];
@@ -894,9 +980,13 @@ export function publicAccessIssues(entries, ctx) {
         }
         const column = (ref) => index.column(entry.table, ref);
         const key = entry.key ?? CUSTOMER_KEY;
-        if (key !== CUSTOMER_KEY && ctx.publicKeys?.[key] === undefined) {
+        if (key !== CUSTOMER_KEY && key !== FORMS_KEY && ctx.publicKeys?.[key] === undefined) {
             out.push({ path: at('key'), message: `"${key}" is not one of the app's publicKeys` });
         }
+        if (key === FORMS_KEY)
+            out.push(...formsEntryIssues(entry, i, entries, ctx.appKey, index));
+        else if (entry.source !== undefined)
+            out.push({ path: at('source'), message: 'a source is said only on a forms entry (key "forms"): the column a form\'s fixed "Source" value goes into' });
         for (const list of ['select', 'writable']) {
             for (const ref of entry[list] ?? []) {
                 if (!has(entry.table, ref))
@@ -906,8 +996,8 @@ export function publicAccessIssues(entries, ctx) {
         // An entry anyone may call (no claim, no parent, no session asked) shows no personal data: the install refuses it too.
         const sessionOnly = entry.level !== undefined && entry.claim === undefined && entry.claimedBy === undefined && entry.visibleWith === undefined;
         const anyone = entry.claim === undefined && entry.visibleWith === undefined && (entry.claimedBy === undefined || entry.claimedBy.optional === true) && !sessionOnly;
-        // An availability entry shows no row, whatever it names.
-        if (anyone && entry.kind !== 'availability') {
+        // An availability entry shows no row, whatever it names; nor does a forms entry, which answers nobody with the row.
+        if (anyone && entry.kind !== 'availability' && key !== FORMS_KEY) {
             // No select shows every column but a code Adminium makes and a secret, as the install reads it.
             const shown = entry.select ??
                 table.columns.filter((c) => c.rules?.['code'] === undefined && c.rules?.['secret'] !== true).map((c) => c.ref);