@wtfalch/foundry 0.76.1 → 0.77.0

package/dist/migrations/0072_audit_host.sql

@@ -0,0 +1,46 @@
+-- @wtfalch/foundry: the audit host (foundry#1110). Three new tables, nothing existing touched, so old and new
+-- releases run side by side. Mirrors src/store/schema.ts's `foundryAuditHostKeys`,
+-- `foundryAuditLedgerRegistrations` and `foundryAuditSealResults`.
+--
+-- A company's audit host key: only its sha256 is kept; the key itself goes to the company's Boule once.
+create table if not exists foundry_audit_host_keys (
+  org_id     text primary key,
+  key_sha256 text not null unique,
+  created_at timestamptz not null default now()
+);
+
+-- A ledger a company's Boule registered (`PUT /v1/audit/ledgers/:app`): where its live database is and the
+-- sealing role it is opened as. The password is not here: it is in the host's held keys at `password_ref`.
+create table if not exists foundry_audit_ledger_registrations (
+  org_id       text not null,
+  entry_key    text not null,
+  copy         text not null,
+  db_host      text not null,
+  db_port      integer not null,
+  db_name      text not null,
+  db_user      text not null,
+  sslmode      text,
+  password_ref text not null,
+  created_at   timestamptz not null default now(),
+  updated_at   timestamptz not null default now(),
+  primary key (org_id, entry_key)
+);
+
+-- Each seal tick's result per ledger, kept for 12 hours (`SEAL_RESULTS_KEPT_HOURS`): what `status` shows.
+create table if not exists foundry_audit_seal_results (
+  id        bigserial primary key,
+  org_id    text not null,
+  entry_key text not null,
+  ledger    text not null,
+  outcome   text not null,
+  tree_size integer,
+  anchored  integer not null default 0,
+  erasures  integer not null default 0,
+  reason    text,
+  at        timestamptz not null
+);
+
+create index if not exists foundry_audit_seal_results_ledger_idx
+  on foundry_audit_seal_results (org_id, entry_key, at desc, id desc);
+create index if not exists foundry_audit_seal_results_at_idx
+  on foundry_audit_seal_results (at);

package/dist/migrations/0074_platform_app_canary.sql

@@ -0,0 +1,11 @@
+-- @wtfalch/foundry: the app-layer canary on the declared platform (foundry#1133).
+-- Mirrors `src/store/schema.ts`'s `foundryDeclaredPlatform` additions.
+-- `app_canary_tag` and `app_canary_sha256` are the pin of the canary Worker
+-- foundry ships (`appCanaryShippedPin()`); both empty means nothing is pinned
+-- yet, and the planner reports that instead of planning the step. Off by
+-- default, like the usage tail Worker.
+
+alter table foundry_declared_platform
+  add column if not exists app_canary_enabled boolean not null default false,
+  add column if not exists app_canary_tag text not null default '',
+  add column if not exists app_canary_sha256 text not null default '';

package/dist/modules/ai.js

@@ -1,5 +1,19 @@
 import { AI_ENTRY_PERMISSIONS, AI_WEBHOOK_PATH } from '../entry-rules.js';
 import { list, setUse, text } from './entry-parts.js';
+/**
+ * Plain words for every permission an app's AI key may hold. A `Record` over the permission list, so a
+ * permission added to {@link AI_ENTRY_PERMISSIONS} fails the typecheck until it has words here.
+ */
+const PERMISSION_WORDS = {
+    'ai.offerings:invoke': {
+        label: 'Use the AI tasks and wait for the answer',
+        help: 'The app asks an AI task and gets the answer back at once.',
+    },
+    'ai.runs:create': {
+        label: 'Start AI work that finishes later',
+        help: 'The app starts longer AI work and gets the result when it is done.',
+    },
+};
 /** `uses.ai`: the app calls the AI tasks set up for the company. */
 export const ai = {
     view: {
@@ -33,7 +47,7 @@ export const ai = {
                 help: 'Leave it empty to allow all of them.',
                 kind: 'list',
                 advanced: true,
-                choices: AI_ENTRY_PERMISSIONS.map((value) => ({ value, label: value })),
+                choices: AI_ENTRY_PERMISSIONS.map((value) => ({ value, ...PERMISSION_WORDS[value] })),
             },
         ],
         adds: [{ name: 'AI tasks', hint: "Run on your company's own AI account." }],

package/dist/modules/assistants.js

@@ -57,6 +57,9 @@ export const assistants = {
         if (signIn?.users !== 'customers') {
             return problem(null, 'Help for AI assistants needs Sign-in for your customers: each customer connects their own assistant. In Sign-in, choose "Your customers". They can sign up themselves or be invited.');
         }
+        if (signIn.team === true) {
+            return problem(null, 'Help for AI assistants is not ready yet for an app your team signs in to as well. In Sign-in, turn off "Your team signs in too".');
+        }
         const onboarding = text(values, 'onboardingPath');
         if (onboarding !== undefined && !isPagePath(onboarding)) {
             return problem('onboardingPath', 'The page must start with "/", such as /onboarding, with no spaces, "?", "#" or "..".');

package/dist/modules/email.d.ts

@@ -1,3 +1,8 @@
 import type { AppModule } from './types.js';
-/** `uses.mail`: the app sends mail from the company's mail domain. */
+/**
+ * `uses.mail`: the app sends mail from the company's mail domain. With every setting at its default the entry
+ * holds `uses.mail: true`, as before; otherwise an {@link EntryMail} holding only the settings that differ.
+ * The sender name and reply-to go to the app's env (`entrySettingsEnv`); the bounce settings are for the
+ * company's mail service.
+ */
 export declare const email: AppModule;

package/dist/modules/email.js

@@ -1,5 +1,11 @@
-import { setUse } from './entry-parts.js';
-/** `uses.mail`: the app sends mail from the company's mail domain. */
+import { MAIL_BOUNCES_DEFAULT, MAIL_BOUNCES_MAX, MAIL_BOUNCE_ALERT_DEFAULT, MAIL_FROM_NAME, MAIL_FROM_NAME_MAX, MAIL_REPLY_TO, MAIL_REPLY_TO_MAX, PERCENT_MAX, PERCENT_MIN, } from '../entry-rules.js';
+import { problem, setUse, text } from './entry-parts.js';
+/**
+ * `uses.mail`: the app sends mail from the company's mail domain. With every setting at its default the entry
+ * holds `uses.mail: true`, as before; otherwise an {@link EntryMail} holding only the settings that differ.
+ * The sender name and reply-to go to the app's env (`entrySettingsEnv`); the bounce settings are for the
+ * company's mail service.
+ */
 export const email = {
     view: {
         id: 'email',
@@ -10,9 +16,86 @@ export const email = {
         runtimes: ['server'],
         requires: [],
         availability: 'ready',
-        fields: [],
+        fields: [
+            {
+                key: 'fromName',
+                label: 'Sender name',
+                help: "The name people see the email come from. Leave it empty to use your company's name.",
+                kind: 'text',
+                max: MAIL_FROM_NAME_MAX,
+                pattern: MAIL_FROM_NAME.source,
+            },
+            {
+                key: 'replyTo',
+                label: 'Replies go to',
+                help: 'An email address, such as help@example.com. Leave it empty to send replies to the sending address.',
+                kind: 'text',
+                max: MAIL_REPLY_TO_MAX,
+                pattern: MAIL_REPLY_TO.source,
+            },
+            {
+                key: 'stopAfterBounces',
+                label: 'Stop sending to an address after this many bounces',
+                help: `An email bounces when it cannot be delivered. From 1 to ${MAIL_BOUNCES_MAX}.`,
+                kind: 'number',
+                default: MAIL_BOUNCES_DEFAULT,
+                min: 1,
+                max: MAIL_BOUNCES_MAX,
+            },
+            {
+                key: 'bounceAlertPercent',
+                label: 'Email the owners when more than this share of emails bounce',
+                help: `In percent of a week's email, from ${PERCENT_MIN} to ${PERCENT_MAX}.`,
+                kind: 'number',
+                default: MAIL_BOUNCE_ALERT_DEFAULT,
+                min: PERCENT_MIN,
+                max: PERCENT_MAX,
+            },
+        ],
         adds: [{ name: 'Sending email', hint: "From your company's own mail address." }],
     },
-    toEntry: (entry, values) => setUse(entry, 'mail', values === null ? undefined : true),
-    fromEntry: (entry) => (entry.uses?.mail === true ? {} : null),
+    check(values) {
+        const name = text(values, 'fromName');
+        if (name !== undefined && name.trim() !== name) {
+            return problem('fromName', '"Sender name" cannot start or end with a space.');
+        }
+        return null;
+    },
+    toEntry(entry, values) {
+        if (values === null)
+            return setUse(entry, 'mail', undefined);
+        const next = {};
+        const fromName = text(values, 'fromName');
+        const replyTo = text(values, 'replyTo');
+        if (fromName !== undefined)
+            next.fromName = fromName;
+        if (replyTo !== undefined)
+            next.replyTo = replyTo;
+        const bounces = values.stopAfterBounces;
+        if (typeof bounces === 'number' && bounces !== MAIL_BOUNCES_DEFAULT) {
+            next.stopAfterBounces = bounces;
+        }
+        const alert = values.bounceAlertPercent;
+        if (typeof alert === 'number' && alert !== MAIL_BOUNCE_ALERT_DEFAULT) {
+            next.bounceAlertPercent = alert;
+        }
+        return setUse(entry, 'mail', Object.keys(next).length === 0 ? true : next);
+    },
+    fromEntry(entry) {
+        const used = entry.uses?.mail;
+        if (!used)
+            return null;
+        if (used === true)
+            return {};
+        const values = {};
+        if (used.fromName !== undefined)
+            values.fromName = used.fromName;
+        if (used.replyTo !== undefined)
+            values.replyTo = used.replyTo;
+        if (used.stopAfterBounces !== undefined)
+            values.stopAfterBounces = used.stopAfterBounces;
+        if (used.bounceAlertPercent !== undefined)
+            values.bounceAlertPercent = used.bounceAlertPercent;
+        return values;
+    },
 };

package/dist/modules/files.js

@@ -1,5 +1,31 @@
-import { FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS } from '../entry-rules.js';
+import { FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS, FILES_SHARE_LINK_DAYS, FILES_SHARE_LINK_DAYS_DEFAULT, FILES_SPACE_ALERT_DEFAULT, PERCENT_MAX, PERCENT_MIN, } from '../entry-rules.js';
 import { list, setUse } from './entry-parts.js';
+/**
+ * Plain words for every permission an app's files key may hold. A `Record` over the permission list, so a
+ * permission added to {@link FILES_ENTRY_PERMISSIONS} fails the typecheck until it has words here.
+ */
+const PERMISSION_WORDS = {
+    'files.collections:read': {
+        label: 'See the folders',
+        help: 'The app lists its folders and what each one holds.',
+    },
+    'files.files:read': {
+        label: 'See the files',
+        help: 'The app reads the names and details of the files.',
+    },
+    'files.files:download': {
+        label: 'Open files',
+        help: 'The app gets the content of a file to show or send it.',
+    },
+    'files.files:upload': { label: 'Add files', help: 'The app saves new files.' },
+    'files.files:replace': {
+        label: 'Replace files',
+        help: 'The app saves a new version over a file it already has.',
+    },
+    'files.files:delete': { label: 'Delete files', help: 'The app removes files.' },
+};
+const NEVER = 'never';
+const dayWords = (days) => (days === 1 ? '1 day' : `${days} days`);
 /** `uses.files`: the app keeps files (uploads, documents) in folders of its own. */
 export const files = {
     view: {
@@ -20,6 +46,37 @@ export const files = {
                 required: true,
                 pattern: FILES_COLLECTION_NAME.source,
             },
+            {
+                key: 'shareLinkDays',
+                label: 'Share links stop working after',
+                help: 'How long a link to a shared file works, unless the person who shares it picks another time.',
+                kind: 'choice',
+                default: String(FILES_SHARE_LINK_DAYS_DEFAULT),
+                choices: [
+                    ...FILES_SHARE_LINK_DAYS.map((days) => ({ value: String(days), label: dayWords(days) })),
+                    {
+                        value: NEVER,
+                        label: 'Never',
+                        help: 'A link works until someone stops sharing the file.',
+                    },
+                ],
+            },
+            {
+                key: 'shareLinkPick',
+                label: 'People may pick another time when they share',
+                help: 'Off: every link stops working after the time above.',
+                kind: 'switch',
+                default: true,
+            },
+            {
+                key: 'spaceAlertPercent',
+                label: 'Email the owners when this much of the space is used',
+                help: `In percent, from ${PERCENT_MIN} to ${PERCENT_MAX}.`,
+                kind: 'number',
+                default: FILES_SPACE_ALERT_DEFAULT,
+                min: PERCENT_MIN,
+                max: PERCENT_MAX,
+            },
             {
                 key: 'shareHost',
                 label: 'Share links on your own address',
@@ -34,7 +91,7 @@ export const files = {
                 help: 'Leave it empty to allow all of them.',
                 kind: 'list',
                 advanced: true,
-                choices: FILES_ENTRY_PERMISSIONS.map((value) => ({ value, label: value })),
+                choices: FILES_ENTRY_PERMISSIONS.map((value) => ({ value, ...PERMISSION_WORDS[value] })),
             },
         ],
         adds: [{ name: 'File storage', hint: 'Only this app reaches its folders.' }],
@@ -48,6 +105,19 @@ export const files = {
             next.permissions = permissions;
         if (values.shareHost === true)
             next.shareHost = true;
+        // A setting at its default is left out, so an entry saved before these settings plans as it did.
+        const days = values.shareLinkDays;
+        if (days === NEVER)
+            next.shareLinkDays = null;
+        else if (typeof days === 'string' && days !== String(FILES_SHARE_LINK_DAYS_DEFAULT)) {
+            next.shareLinkDays = Number(days);
+        }
+        if (values.shareLinkPick === false)
+            next.shareLinkPick = false;
+        const alert = values.spaceAlertPercent;
+        if (typeof alert === 'number' && alert !== FILES_SPACE_ALERT_DEFAULT) {
+            next.spaceAlertPercent = alert;
+        }
         return setUse(entry, 'files', next);
     },
     fromEntry(entry) {
@@ -59,6 +129,13 @@ export const files = {
             values.permissions = [...used.permissions];
         if (used.shareHost !== undefined)
             values.shareHost = used.shareHost;
+        if (used.shareLinkDays !== undefined) {
+            values.shareLinkDays = used.shareLinkDays === null ? NEVER : String(used.shareLinkDays);
+        }
+        if (used.shareLinkPick !== undefined)
+            values.shareLinkPick = used.shareLinkPick;
+        if (used.spaceAlertPercent !== undefined)
+            values.spaceAlertPercent = used.spaceAlertPercent;
         return values;
     },
 };

package/dist/modules/index.js

@@ -11,6 +11,7 @@ import { files } from './files.js';
 import { jobs } from './jobs.js';
 import { organisations } from './organisations.js';
 import { SECRET_OUTPUTS, referenceProblem } from './outputs.js';
+import { reporting } from './reporting.js';
 import { repository } from './repository.js';
 import { signIn } from './sign-in.js';
 import { signedRecords } from './signed-records.js';
@@ -30,6 +31,7 @@ export const MODULES = [
     email,
     jobs,
     analytics,
+    reporting,
     ai,
     organisations,
     audit,
@@ -65,6 +67,11 @@ function fieldProblem(field, value) {
         case 'number':
             if (typeof value !== 'number' || !Number.isFinite(value))
                 return `${name} must be a number.`;
+            if (!Number.isInteger(value))
+                return `${name} must be a whole number.`;
+            if (field.min !== undefined && value < field.min) {
+                return `${name} must be at least ${field.min}.`;
+            }
             return field.max !== undefined && value > field.max
                 ? `${name} may be at most ${field.max}.`
                 : null;

package/dist/modules/jobs.d.ts

@@ -1,3 +1,7 @@
 import type { AppModule } from './types.js';
-/** `uses.jobs`: the app is a project of its own in the jobs scheduler. */
+/**
+ * `uses.jobs`: the app is a project of its own in the jobs scheduler. Its settings are for that project: with
+ * every one at its default the entry holds `uses.jobs: true`, as before; otherwise an {@link EntryJobs}
+ * holding only the settings that differ.
+ */
 export declare const jobs: AppModule;

package/dist/modules/jobs.js

@@ -1,5 +1,10 @@
+import { JOBS_PAUSE_AFTER_DEFAULT, JOBS_PAUSE_AFTER_MAX, JOBS_RETRIES_DEFAULT, JOBS_RETRIES_MAX, } from '../entry-rules.js';
 import { setUse } from './entry-parts.js';
-/** `uses.jobs`: the app is a project of its own in the jobs scheduler. */
+/**
+ * `uses.jobs`: the app is a project of its own in the jobs scheduler. Its settings are for that project: with
+ * every one at its default the entry holds `uses.jobs: true`, as before; otherwise an {@link EntryJobs}
+ * holding only the settings that differ.
+ */
 export const jobs = {
     view: {
         id: 'jobs',
@@ -10,7 +15,40 @@ export const jobs = {
         runtimes: ['server'],
         requires: [],
         availability: 'ready',
-        fields: [],
+        fields: [
+            {
+                key: 'retries',
+                label: 'Tries again when a job fails',
+                help: `How many more times we try a job that failed, from 0 to ${JOBS_RETRIES_MAX}.`,
+                kind: 'number',
+                default: JOBS_RETRIES_DEFAULT,
+                min: 0,
+                max: JOBS_RETRIES_MAX,
+            },
+            {
+                key: 'alertOwners',
+                label: 'Email the owners when a job failed every try',
+                kind: 'switch',
+                default: true,
+            },
+            {
+                key: 'pauseOnFailures',
+                label: 'Pause a job that keeps failing',
+                help: 'A paused job waits until someone resumes it on the Jobs page.',
+                kind: 'switch',
+                default: false,
+            },
+            {
+                key: 'pauseAfterFailures',
+                label: 'Pause it after this many failed runs in a row',
+                help: `From 1 to ${JOBS_PAUSE_AFTER_MAX}.`,
+                kind: 'number',
+                default: JOBS_PAUSE_AFTER_DEFAULT,
+                min: 1,
+                max: JOBS_PAUSE_AFTER_MAX,
+                showWhen: { key: 'pauseOnFailures', equals: true },
+            },
+        ],
         adds: [
             {
                 name: 'A scheduler',
@@ -18,6 +56,38 @@ export const jobs = {
             },
         ],
     },
-    toEntry: (entry, values) => setUse(entry, 'jobs', values === null ? undefined : true),
-    fromEntry: (entry) => (entry.uses?.jobs === true ? {} : null),
+    toEntry(entry, values) {
+        if (values === null)
+            return setUse(entry, 'jobs', undefined);
+        const next = {};
+        if (typeof values.retries === 'number' && values.retries !== JOBS_RETRIES_DEFAULT) {
+            next.retries = values.retries;
+        }
+        if (values.alertOwners === false)
+            next.alertOwners = false;
+        if (values.pauseOnFailures === true) {
+            next.pauseAfterFailures =
+                typeof values.pauseAfterFailures === 'number'
+                    ? values.pauseAfterFailures
+                    : JOBS_PAUSE_AFTER_DEFAULT;
+        }
+        return setUse(entry, 'jobs', Object.keys(next).length === 0 ? true : next);
+    },
+    fromEntry(entry) {
+        const used = entry.uses?.jobs;
+        if (!used)
+            return null;
+        if (used === true)
+            return {};
+        const values = {};
+        if (used.retries !== undefined)
+            values.retries = used.retries;
+        if (used.alertOwners !== undefined)
+            values.alertOwners = used.alertOwners;
+        if (typeof used.pauseAfterFailures === 'number') {
+            values.pauseOnFailures = true;
+            values.pauseAfterFailures = used.pauseAfterFailures;
+        }
+        return values;
+    },
 };

package/dist/modules/reporting.d.ts

@@ -0,0 +1,9 @@
+import type { AppModule } from './types.js';
+/**
+ * `uses.reporting` on a Worker app: the app sends its errors to the company's own reporting backend, and Boule
+ * shows them on the app's Errors page. Boule installs a site key on each copy of the app (`REPORTING_URL`,
+ * `REPORTING_SITE_KEY`; site = the app key, environment `production` for live and `stage` for the workspace);
+ * foundry only sets up the backend. One on/off module, no fields. A server app declares `uses.reporting` itself
+ * and gets its key from foundry.
+ */
+export declare const reporting: AppModule;

package/dist/modules/reporting.js

@@ -0,0 +1,29 @@
+import { setUse } from './entry-parts.js';
+/**
+ * `uses.reporting` on a Worker app: the app sends its errors to the company's own reporting backend, and Boule
+ * shows them on the app's Errors page. Boule installs a site key on each copy of the app (`REPORTING_URL`,
+ * `REPORTING_SITE_KEY`; site = the app key, environment `production` for live and `stage` for the workspace);
+ * foundry only sets up the backend. One on/off module, no fields. A server app declares `uses.reporting` itself
+ * and gets its key from foundry.
+ */
+export const reporting = {
+    view: {
+        id: 'reporting',
+        name: 'Report errors',
+        line: 'We keep the errors the app runs into, so you can see what went wrong and when.',
+        category: 'Data',
+        icon: 'alert',
+        runtimes: ['worker'],
+        requires: [],
+        availability: 'ready',
+        fields: [],
+        adds: [
+            {
+                name: 'Errors',
+                hint: 'What went wrong in the app, how often and since when, on its Errors page. Kept in your own company only.',
+            },
+        ],
+    },
+    toEntry: (entry, values) => setUse(entry, 'reporting', values === null ? undefined : true),
+    fromEntry: (entry) => (entry.uses?.reporting === true ? {} : null),
+};

package/dist/modules/sign-in.js

@@ -50,6 +50,14 @@ export const signIn = {
                     },
                 ],
             },
+            {
+                key: 'team',
+                label: 'Your team signs in too',
+                help: 'The people in your company sign in to the same app with their own company account.',
+                kind: 'switch',
+                showWhen: forCustomers,
+                runtimes: ['server'],
+            },
             {
                 key: 'registration',
                 label: 'Who can make an account',
@@ -142,6 +150,9 @@ export const signIn = {
     },
     check(values) {
         const customers = values.users === 'customers';
+        if (values.team === true && !customers) {
+            return problem('team', 'Your team already signs in when "Who signs in" is "Your team". Turn this on for an app your customers sign in to.');
+        }
         if (!customers && values.registration === 'open') {
             return problem('registration', 'Only customers can make their own account. For your team, choose "Only people you invite".');
         }
@@ -195,9 +206,13 @@ export const signIn = {
         }
         // The parts other modules own (mcp, workspaces) and the operator's replacesBrokerEntry stay.
         const kept = omit(entry.uses?.auth ?? {}, 'signIn', 'signIns', 'secondFactor', 'room');
+        // ADR 0003: customers with the team beside them is both audiences; one audience stays the single value.
+        const users = values.users === 'customers' && values.team === true
+            ? ['customers', 'staff']
+            : values.users;
         const auth = {
             ...kept,
-            users: values.users,
+            users,
             registration: values.registration,
         };
         const methods = methodsOf(values);
@@ -219,8 +234,11 @@ export const signIn = {
         const auth = entry.uses?.auth;
         if (!auth)
             return null;
+        const listed = Array.isArray(auth.users) ? auth.users : [auth.users];
+        const audiences = ['customers', 'staff'].filter((a) => listed.includes(a));
         const values = {
-            users: auth.users,
+            users: audiences.includes('customers') ? 'customers' : 'staff',
+            ...(audiences.length === 2 ? { team: true } : {}),
             registration: auth.registration,
             methods: auth.signIns ?? [auth.signIn ?? 'password'],
             secondFactor: auth.secondFactor ?? 'off',

package/dist/modules/types.d.ts

@@ -34,6 +34,8 @@ export interface ModuleField {
     pattern?: string;
     /** The longest text, the most list items, or the largest number. */
     max?: number;
+    /** For `number`: the smallest. Every `number` field is a whole number. */
+    min?: number;
     /** Shown only while another field of the same module has this value. */
     showWhen?: {
         key: string;

package/dist/modules/workspaces.js

@@ -40,6 +40,9 @@ export const workspaces = {
         if (modules['sign-in']?.users !== 'customers') {
             return problem(null, 'Workspaces are for your customers. In Sign-in, choose "Your customers" first.');
         }
+        if (modules['sign-in']?.team === true) {
+            return problem(null, 'Workspaces are not ready yet for an app your team signs in to as well. In Sign-in, turn off "Your team signs in too".');
+        }
         const roles = list(values, 'roles') ?? [];
         const seen = new Set();
         for (const [index, role] of roles.entries()) {