pgkiln 0.52.0 → 0.53.0

package/src/cli/mcp.ts

@@ -17,6 +17,7 @@ const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 /** Cap on the text one tool call returns, so a large application does not flood the agent's context. */
 const MAX_TEXT = 200_000;
 const QUERY_TIMEOUT = '10s';
+const pgIdent = (n: string) => `"${n.replace(/"/g, '""')}"`;
 
 const version = () => JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version as string;
 
@@ -139,10 +140,35 @@ export function searchDocs(query: string, max: number) {
 /** Column names whose values run_query never shows (password hashes, tokens, secrets). */
 const SENSITIVE = /password|secret|token|hash|private_key|api_key|client_secret/i;
 
-export async function readOnlyQuery(db: Db, sql: string, maxRows: number) {
+/**
+ * (sprint 119, WS-13) Whom a query runs as: an application's database role, with meta.app_id(), meta.app_user() and
+ * meta.has_role() (the user's roles in the application) set, so grants, column privileges, row level security and
+ * masking views apply as they do to that user's pages. It shows the agent what the user sees; it is no sandbox, as
+ * the MCP server itself connects as pgkiln's owner.
+ */
+export interface QueryIdentity { appId: number; dbRole: string; user: string }
+
+/** The identity of `user` in the application `alias`; an application without a database role is refused. */
+export async function queryIdentity(db: Db, alias: string, user: string | undefined): Promise<QueryIdentity> {
+  const a = (await db.query(`select id, db_role from meta.app where alias = $1`, [alias])).rows[0];
+  if (!a) throw new ToolError(`no application ${alias}`);
+  if (!a.db_role) throw new ToolError(`${alias} runs without a database role, so its users see what pgkiln's owner sees: give it one (Settings → Security) to run as its users`);
+  return { appId: a.id, dbRole: a.db_role, user: user?.trim() || 'nobody' };
+}
+
+export async function readOnlyQuery(db: Db, sql: string, maxRows: number, as?: QueryIdentity) {
   // the select takes a snapshot, after which "set transaction read write" is refused
   await db.query(`begin transaction read only; set local statement_timeout = '${QUERY_TIMEOUT}'; select 1`);
   try {
+    if (as) {
+      await db.query(
+        `select set_config('pgkiln.app_id', $1, true), set_config('pgkiln.app_user', $2, true), set_config('pgkiln.session_id', '', true),
+                -- meta.has_role(): the user's roles in the application (meta.account_roles), as for an API token
+                set_config('request.jwt.claims', json_build_object('sub', $2::text)::text, true)`,
+        [String(as.appId), as.user],
+      );
+      await db.query(`set local role ${pgIdent(as.dbRole)}`);
+    }
     // the extended protocol runs exactly one statement, so a "commit; delete …"
     // cannot end the read-only transaction and go on (pg would use the simple
     // protocol, which runs them all, for a query without parameters)
@@ -521,17 +547,27 @@ export const TOOLS: Tool[] = [
     description:
       `Runs one SQL statement in a read-only transaction (rolled back, ${QUERY_TIMEOUT} timeout) and returns the rows as JSON. ` +
       'Use it to look at data and at the meta schema; it cannot change anything. Values of columns named like password, secret, token or hash are hidden. ' +
-      'Bind variables (:P1_X) are not replaced: use literals.',
+      'Bind variables (:P1_X) are not replaced: use literals. ' +
+      'With alias (and user), the query runs as that application\'s database role for that user, with meta.app_user() and meta.has_role() set: ' +
+      'grants, column privileges, row level security and masking views apply as on the user\'s pages. Without, it runs as pgkiln\'s owner and sees everything.',
     inputSchema: {
       type: 'object',
-      properties: { sql: { type: 'string' }, max_rows: { type: 'integer', description: 'default 50, at most 500' } },
+      properties: {
+        sql: { type: 'string' },
+        max_rows: { type: 'integer', description: 'default 50, at most 500' },
+        alias: { type: 'string', description: 'run as this application\'s database role (list_apps shows the aliases)' },
+        user: { type: 'string', description: 'with alias: the signed-in user (meta.app_user(); their roles in the application for meta.has_role()); default nobody' },
+      },
       required: ['sql'],
     },
     annotations: { readOnlyHint: true },
     async run(a) {
       const sql = str(a, 'sql', true)!;
       const max = int(a, 'max_rows', 50, 500);
-      return withDb(async (db) => cap(stableJson(await readOnlyQuery(db, sql, max))));
+      const alias = str(a, 'alias');
+      const user = str(a, 'user');
+      if (user && !alias) throw new ToolError('user needs alias: the application whose user it is');
+      return withDb(async (db) => cap(stableJson(await readOnlyQuery(db, sql, max, alias ? await queryIdentity(db, alias, user) : undefined))));
     },
   },
   {

package/src/cli/only.ts

@@ -0,0 +1,52 @@
+// (sprint 116, WS-14) pgkiln import <dir> --replace --only <path>: a file-level
+// import (APEX 26.2: APEXlang file-level import). Only the named page or
+// component files of a directory export change; everything else stays as it is
+// in the database. How: the application is exported in the directory's style,
+// the named files are taken from the directory (and removed where the directory
+// no longer has them), and the merged files are imported with --replace as usual.
+import type { FileMap } from '../appfiles.ts';
+import { UsageError } from './apps.ts';
+
+/**
+ * What an --only argument selects: "pages/12" (or "page 12", "12") is page 12's directory, whatever its
+ * name; any other path is a file or a directory of the export ("shared/lovs/jobs.yaml", "shared/lovs").
+ */
+export function onlyMatcher(arg: string): { label: string; test: (path: string) => boolean } {
+  const a = arg.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+  const page = /^(?:pages?[/ ]?)?(\d{1,9})$/.exec(a);
+  if (page) {
+    const prefix = `pages/${String(Number(page[1])).padStart(4, '0')}-`;
+    return { label: `page ${Number(page[1])}`, test: (p) => p.startsWith(prefix) && p.indexOf('/', prefix.length) > 0 };
+  }
+  if (!a || a.startsWith('/') || a.split('/').includes('..')) throw new UsageError(`--only ${arg}: a path inside the export directory, e.g. pages/12 or shared/lovs/jobs.yaml`);
+  if (a === 'pgkiln.json') throw new UsageError('--only pgkiln.json: the marker file is not a component');
+  return { label: a, test: (p) => p === a || p.startsWith(`${a}/`) };
+}
+
+/**
+ * The files to import: the application's current files with the selected ones replaced by the directory's.
+ * Refuses a selection that matches nothing on either side (a typo) and directories of another style.
+ */
+export function mergeOnly(current: FileMap, incoming: FileMap, only: string[]) {
+  const style = (files: FileMap) => {
+    try {
+      return JSON.parse(files.get('pgkiln.json')?.toString('utf8') ?? '{}').style === 'text' ? 'text' : 'json';
+    } catch {
+      return 'json';
+    }
+  };
+  if (style(current) !== style(incoming)) throw new Error('the application was exported in another style than the directory');
+  const matchers = only.map(onlyMatcher);
+  const selected = (p: string) => matchers.some((m) => m.test(p));
+  for (const m of matchers)
+    if (![...current.keys(), ...incoming.keys()].some((p) => m.test(p))) throw new UsageError(`--only ${m.label}: not in the directory or the application`);
+  const merged: FileMap = new Map([...current].filter(([p]) => !selected(p)));
+  const changed: string[] = [];
+  for (const [p, content] of incoming)
+    if (selected(p)) {
+      merged.set(p, content);
+      if (!current.get(p)?.equals(content)) changed.push(p);
+    }
+  for (const p of current.keys()) if (selected(p) && !incoming.has(p)) changed.push(p);
+  return { files: merged, changed: changed.sort(), labels: matchers.map((m) => m.label) };
+}

package/src/cli/replace.ts

@@ -80,7 +80,11 @@ export const KEPT = ['app_access', 'api_client', 'session', 'sso_pending', 'save
   // (122) Team Development issues of the workspace, linked to the application (workspace data: the workspace export)
   'team_issue',
   // (123) the log of running workflow instances migrated to a newer version (runtime data, like the instances)
-  'workflow_migration'];
+  'workflow_migration',
+  // (125) who changed the application last in the builder (App Builder list: Updated by)
+  'app_change',
+  // (126) outgoing calls the network access lists refused (Administration → Network access; a log, 7 days)
+  'network_refusal'];
 /** Children of pages (replaced with their page). */
 const PAGE_CHILDREN = ['region', 'item', 'button', 'dynamic_action', 'validation', 'process', 'computation', 'branch'];
 /** References into replaced tables from kept data, repointed below: "table.column". */

package/src/datasec.ts

@@ -0,0 +1,343 @@
+import pg from 'pg';
+
+// (sprint 119, WS-13: data security per table, pgkiln's answer to Deep Data Security) A table's rows, columns and
+// values in one place. PostgreSQL has row level security but no column masking, so a table's security here is three
+// layers, all of them ordinary database objects that every client (pages, REST handlers, AutoREST, AI tools, MCP,
+// psql) meets in the same way:
+//
+//   rows     row level security policies (shown here; written in the worksheet; switched on in Table Properties);
+//   columns  column privileges per database role: GRANT/REVOKE SELECT (c, …) and UPDATE (c, …). A column a role may
+//            not read is refused by PostgreSQL ("permission denied"), whoever sends the query;
+//   values   a masking view per table: the table's columns, a masked column as
+//              case when (select meta.has_role('manager')) or … then sal end
+//            for the signed-in user's application roles (meta.has_role). The view runs with its owner's rights, and
+//            its owner is a separate role per schema (<schema>_masking) that is no owner, superuser or BYPASSRLS
+//            role and is a member of the database roles that read the view: so the table's row level security still
+//            applies inside the view (policies use meta.app_user() / meta.has_role(), the caller's settings), and a
+//            database role can read the masked values while its own SELECT on the raw column is revoked.
+//
+// The mask only holds when the database roles of the matrix cannot read the raw column on the table (the second
+// layer): checkSecurity() allows it (an application whose pages still read the table needs it), but the preview
+// says so. The configuration lives in the view's comment ("pgkiln masking view of <table>: {json}"), so it travels
+// with the schema (pg_dump, Generate DDL, the change log) and needs no meta table. Pure apart from readSecurity.
+
+export const MASKS = ['null', 'stars', 'partial'] as const;
+export type Mask = (typeof MASKS)[number];
+export const MASK_LABELS: Record<Mask, string> = { null: 'empty (null)', stars: '***', partial: '*** + last 4' };
+export const MARK = 'pgkiln masking view of ';
+export const NAME_RE = /^[A-Za-z_][A-Za-z0-9_$]{0,62}$/;
+/** An application role (meta.has_role): letters, digits and a few separators; compared in lower case. */
+export const APP_ROLE_RE = /^[\p{L}\p{N}_][\p{L}\p{N}_ .:@-]{0,62}$/u;
+const PRIVS = ['SELECT', 'UPDATE'] as const;
+
+export interface SecColumn { name: string; type: string }
+export interface Policy { name: string; command: string; permissive: string; roles: string; using: string | null; check: string | null }
+/** A database role's privileges on the table: table-wide or on some columns. */
+export interface DbGrant {
+  role: string;
+  tableSelect: boolean;
+  tableUpdate: boolean;
+  colSelect: string[];
+  colUpdate: string[];
+  /** applications that run as this role */
+  apps: string[];
+}
+export interface ColumnMask { see: string[]; others: boolean; mask: Mask }
+export interface MaskConfig { table: string; roles: string[]; cols: Record<string, ColumnMask> }
+export interface TableSecurity {
+  oid: number;
+  schema: string;
+  table: string;
+  owner: string;
+  rls: boolean;
+  forceRls: boolean;
+  columns: SecColumn[];
+  policies: Policy[];
+  grants: DbGrant[];
+  /** roles with privileges that the matrix cannot restrict, and why */
+  excluded: { role: string; why: string }[];
+  /** application roles the applications reading this table check (users.ts roleHints) */
+  appRoles: string[];
+  view: { name: string; config: MaskConfig; columns: string[] } | null;
+  maskRole: string;
+  maskRoleExists: boolean;
+  /** the roles the masking role is a member of */
+  maskMembers: string[];
+}
+export interface SecurityDef {
+  grants: { role: string; select: string[]; update: string[] }[];
+  view: { enabled: boolean; name: string; roles: string[]; cols: Record<string, ColumnMask> };
+}
+
+export const ident = (n: string) => pg.escapeIdentifier(n);
+const lit = (s: string) => pg.escapeLiteral(s);
+const roleIdent = (r: string) => (r === 'PUBLIC' ? 'public' : ident(r));
+
+/** The masking role of a schema: <schema>_masking (cut, with a hash, when the name would be too long). */
+export function maskRoleName(schema: string) {
+  const name = `${schema}_masking`;
+  if (Buffer.byteLength(name) <= 63) return name;
+  let h = 0;
+  for (const ch of schema) h = (h * 31 + ch.codePointAt(0)!) >>> 0;
+  return `${schema.slice(0, 40)}_${h.toString(36)}_masking`;
+}
+
+/** The comment's configuration, checked; null when it is not one of ours or is broken. */
+export function parseConfig(comment: string | null, table: string): MaskConfig | null {
+  if (!comment?.startsWith(MARK)) return null;
+  const colon = comment.indexOf(': {');
+  if (colon < 0 || comment.slice(MARK.length, colon) !== table) return null;
+  try {
+    const x = JSON.parse(comment.slice(colon + 2));
+    if (x?.table !== table || !Array.isArray(x.roles) || typeof x.cols !== 'object' || !x.cols) return null;
+    const roles = (x.roles as unknown[]).filter((r): r is string => typeof r === 'string' && APP_ROLE_RE.test(r)).map((r) => r.toLowerCase());
+    const cols: Record<string, ColumnMask> = {};
+    for (const [c, m] of Object.entries(x.cols as Record<string, any>)) {
+      if (!m || !Array.isArray(m.see)) continue;
+      cols[c] = {
+        see: m.see.filter((r: unknown): r is string => typeof r === 'string' && roles.includes(r)),
+        others: m.others === true,
+        mask: MASKS.includes(m.mask) ? m.mask : 'null',
+      };
+    }
+    return { table, roles, cols };
+  } catch {
+    return null;
+  }
+}
+
+/** The comment that marks a masking view (and holds its configuration). */
+export const configComment = (c: MaskConfig) => {
+  // one spelling per configuration (keys in a fixed order), so an unchanged configuration compares equal
+  const cols = Object.fromEntries(Object.keys(c.cols).sort().map((k) => [k, { mask: c.cols[k].mask, see: [...c.cols[k].see].sort(), others: c.cols[k].others }]));
+  return `${MARK}${c.table}: ${JSON.stringify({ table: c.table, roles: [...c.roles].sort(), cols })}`;
+};
+
+type Q = { query: <T extends pg.QueryResultRow = any>(sql: string, params?: unknown[]) => Promise<pg.QueryResult<T>> };
+
+/**
+ * A table's security as the catalog has it. `appDbRoles`: the database roles of the workspace's applications
+ * (shown as matrix rows even without privileges); `appRoles`: the application roles they check.
+ */
+export async function readSecurity(db: Q, ref: string, appDbRoles: { role: string; alias: string }[], appRoles: string[]): Promise<TableSecurity | null> {
+  const t = (await db.query(
+    `select c.oid::int as oid, n.nspname as schema, c.relname as table, pg_get_userbyid(c.relowner) as owner, c.relrowsecurity as rls, c.relforcerowsecurity as force
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace where c.oid = to_regclass($1) and c.relkind in ('r', 'p')`, [ref])).rows[0];
+  if (!t) return null;
+  const columns = (await db.query<SecColumn>(
+    `select attname as name, format_type(atttypid, atttypmod) as type from pg_attribute where attrelid = $1 and attnum > 0 and not attisdropped order by attnum`, [t.oid])).rows;
+  const policies = (await db.query<Policy>(
+    `select policyname as name, cmd as command, permissive, array_to_string(roles, ', ') as roles, qual as using, with_check as check
+       from pg_policies where schemaname = $1 and tablename = $2 order by policyname`, [t.schema, t.table])).rows;
+  const tableAcl = (await db.query<{ role: string; priv: string }>(
+    `select coalesce(r.rolname, 'PUBLIC') as role, a.privilege_type as priv
+       from pg_class c cross join lateral aclexplode(c.relacl) a left join pg_roles r on r.oid = a.grantee
+      where c.oid = $1 and a.privilege_type in ('SELECT', 'UPDATE')`, [t.oid])).rows;
+  const colAcl = (await db.query<{ role: string; col: string; priv: string }>(
+    `select coalesce(r.rolname, 'PUBLIC') as role, att.attname as col, a.privilege_type as priv
+       from pg_attribute att cross join lateral aclexplode(att.attacl) a left join pg_roles r on r.oid = a.grantee
+      where att.attrelid = $1 and att.attnum > 0 and not att.attisdropped and a.privilege_type in ('SELECT', 'UPDATE')
+      order by att.attnum`, [t.oid])).rows;
+  const maskRole = maskRoleName(t.schema);
+  // roles the matrix cannot restrict: the owner and whoever has its privileges, superusers, BYPASSRLS roles
+  const names = [...new Set([...tableAcl.map((r) => r.role), ...colAcl.map((r) => r.role), ...appDbRoles.map((a) => a.role)])].filter((r) => r !== 'PUBLIC');
+  const special = new Map((await db.query<{ role: string; why: string | null }>(
+    `select r.rolname as role,
+            case when r.rolsuper then 'superuser' when r.rolbypassrls then 'bypasses row level security'
+                 when pg_has_role(r.oid, $2::regrole, 'USAGE') then 'owns the table' end as why
+       from pg_roles r where r.rolname = any ($1)`, [names, t.owner])).rows.map((r) => [r.role, r.why]));
+  const excluded: { role: string; why: string }[] = [];
+  const grants = new Map<string, DbGrant>();
+  const row = (role: string) => {
+    let g = grants.get(role);
+    if (!g) grants.set(role, (g = { role, tableSelect: false, tableUpdate: false, colSelect: [], colUpdate: [], apps: [] }));
+    return g;
+  };
+  const usable = (role: string) => {
+    if (role === maskRole) return false;
+    if (role === 'PUBLIC') return true;
+    if (!special.has(role)) return false; // a dropped role
+    const why = special.get(role);
+    if (why) {
+      if (!excluded.some((x) => x.role === role)) excluded.push({ role, why });
+      return false;
+    }
+    return true;
+  };
+  for (const a of tableAcl) if (usable(a.role)) a.priv === 'SELECT' ? (row(a.role).tableSelect = true) : (row(a.role).tableUpdate = true);
+  for (const a of colAcl) if (usable(a.role)) (a.priv === 'SELECT' ? row(a.role).colSelect : row(a.role).colUpdate).push(a.col);
+  for (const a of appDbRoles) if (usable(a.role)) row(a.role).apps.push(a.alias);
+  // the masking view: a view in the table's schema whose comment names this table
+  let view: TableSecurity['view'] = null;
+  for (const v of (await db.query<{ oid: number; name: string; comment: string | null }>(
+    `select c.oid::int as oid, c.relname as name, obj_description(c.oid, 'pg_class') as comment from pg_class c
+      where c.relnamespace = (select relnamespace from pg_class where oid = $1) and c.relkind = 'v'
+        and obj_description(c.oid, 'pg_class') like $2 order by c.relname`, [t.oid, `${MARK.replace(/_/g, '\\_')}%`])).rows) {
+    const config = parseConfig(v.comment, t.table);
+    if (!config) continue;
+    const cols = (await db.query<{ name: string }>(`select attname as name from pg_attribute where attrelid = $1 and attnum > 0 and not attisdropped order by attnum`, [v.oid])).rows.map((r) => r.name);
+    view = { name: v.name, config, columns: cols };
+    break;
+  }
+  const mr = (await db.query<{ exists: boolean; members: string[] | null }>(
+    `select exists (select from pg_roles where rolname = $1) as exists,
+            (select array_agg(g.rolname order by g.rolname) from pg_auth_members m join pg_roles g on g.oid = m.roleid join pg_roles u on u.oid = m.member where u.rolname = $1) as members`,
+    [maskRole])).rows[0];
+  const order = (g: DbGrant) => (g.role === 'PUBLIC' ? 'zz' : g.apps.length ? `a${g.role}` : `b${g.role}`);
+  return {
+    oid: t.oid, schema: t.schema, table: t.table, owner: t.owner, rls: t.rls, forceRls: t.force, columns, policies,
+    grants: [...grants.values()].sort((x, y) => order(x).localeCompare(order(y))), excluded,
+    appRoles: [...new Set([...appRoles.map((r) => r.toLowerCase()), ...(view?.config.roles ?? [])])].sort(),
+    view, maskRole, maskRoleExists: mr.exists, maskMembers: mr.members ?? [],
+  };
+}
+
+/** The current state as a definition (what the matrix shows before a change). */
+export function currentDef(cur: TableSecurity): SecurityDef {
+  const all = cur.columns.map((c) => c.name);
+  return {
+    grants: cur.grants.map((g) => ({ role: g.role, select: g.tableSelect ? all : all.filter((c) => g.colSelect.includes(c)), update: g.tableUpdate ? all : all.filter((c) => g.colUpdate.includes(c)) })),
+    view: {
+      enabled: !!cur.view,
+      name: cur.view?.name ?? `${cur.table}_masked`.slice(0, 63),
+      roles: cur.appRoles,
+      cols: Object.fromEntries(Object.entries(cur.view?.config.cols ?? {}).filter(([c]) => all.includes(c))),
+    },
+  };
+}
+
+/** Whether an application role sees a column's values (roles not in the configuration count as "others"). */
+export function sees(def: SecurityDef['view'], col: string, role: string | null): boolean {
+  const m = def.cols[col];
+  if (!m) return true;
+  if (role === null) return m.others;
+  return m.see.includes(role) || (!def.roles.includes(role) && m.others);
+}
+
+/** Columns with a mask: some listed role or the others do not see them. */
+export function maskedColumns(v: SecurityDef['view']) {
+  return Object.entries(v.cols).filter(([, m]) => !m.others || v.roles.some((r) => !m.see.includes(r))).map(([c]) => c);
+}
+
+const hasRole = (r: string) => `(select meta.has_role(${lit(r)}))`;
+
+/** The condition under which the signed-in user sees a column: one of the roles that see it, or none of the listed roles. */
+export function seesSql(roles: string[], m: ColumnMask): string {
+  const parts = roles.filter((r) => m.see.includes(r)).map(hasRole);
+  if (m.others) parts.push(roles.length ? `not (${roles.map(hasRole).join(' or ')})` : 'true');
+  return parts.length ? parts.join(' or ') : 'false';
+}
+
+/** The view's SELECT list entry for a column. */
+export function columnSql(col: string, roles: string[], m: ColumnMask | undefined): string {
+  const c = `t.${ident(col)}`;
+  if (!m || (m.others && roles.every((r) => m.see.includes(r)))) return c;
+  const cond = seesSql(roles, m);
+  if (m.mask === 'stars') return `case when ${cond} then ${c}::text else '***' end as ${ident(col)}`;
+  if (m.mask === 'partial') return `case when ${cond} then ${c}::text else '***' || right(${c}::text, 4) end as ${ident(col)}`;
+  return `case when ${cond} then ${c} end as ${ident(col)}`;
+}
+
+/** What is wrong with a definition (against the catalog's state); `taken`: relation names in the schema. */
+export function checkSecurity(def: SecurityDef, cur: TableSecurity, taken: string[]): string[] {
+  const errors: string[] = [];
+  const cols = new Set(cur.columns.map((c) => c.name));
+  const roles = new Set(cur.grants.map((g) => g.role));
+  for (const g of def.grants) {
+    if (!roles.has(g.role)) errors.push(`${g.role} is not a database role this page can change.`);
+    if ([...g.select, ...g.update].some((c) => !cols.has(c))) errors.push(`A column of ${g.role} is not in the table.`);
+  }
+  const v = def.view;
+  for (const r of v.roles) if (!APP_ROLE_RE.test(r) || r !== r.toLowerCase()) errors.push(`"${r}" is not a valid application role (letters, digits, _ . : @ - and spaces; lower case).`);
+  for (const [c, m] of Object.entries(v.cols)) {
+    if (!cols.has(c)) errors.push(`${c} is not a column of the table.`);
+    if (!MASKS.includes(m.mask)) errors.push(`Unknown mask for ${c}.`);
+    if (m.see.some((r) => !v.roles.includes(r))) errors.push(`A role that sees ${c} is not in the list.`);
+  }
+  if (v.enabled) {
+    if (!NAME_RE.test(v.name)) errors.push('The masking view needs a name of letters, digits, _ and $ (at most 63).');
+    else if (v.name === cur.table) errors.push('The masking view needs a name other than the table\'s.');
+    else if (taken.includes(v.name) && v.name !== cur.view?.name) errors.push(`${cur.schema}.${v.name} already exists.`);
+  }
+  return errors;
+}
+
+/** The roles that read through the view: database roles that may read some column of the table (after the change). */
+const viewReaders = (def: SecurityDef) => def.grants.filter((g) => g.select.length).map((g) => g.role);
+
+/**
+ * The statements that turn the catalog's state into the definition, and warnings about what they leave open.
+ * Order: the table's column privileges, then the masking view (dropped first, so a script starts with schema DDL).
+ */
+export function securitySql(def: SecurityDef, cur: TableSecurity): { statements: string[]; warnings: string[] } {
+  const out: string[] = [];
+  const warnings: string[] = [];
+  const T = `${ident(cur.schema)}.${ident(cur.table)}`;
+  const all = cur.columns.map((c) => c.name);
+  const list = (cs: string[]) => cs.map(ident).join(', ');
+  for (const want of def.grants) {
+    const g = cur.grants.find((x) => x.role === want.role)!;
+    for (const p of PRIVS) {
+      const w = new Set(p === 'SELECT' ? want.select : want.update);
+      const tableWide = p === 'SELECT' ? g.tableSelect : g.tableUpdate;
+      const have = new Set(tableWide ? all : p === 'SELECT' ? g.colSelect : g.colUpdate);
+      const R = roleIdent(want.role);
+      if (all.every((c) => w.has(c))) {
+        if (!tableWide && !all.every((c) => have.has(c))) out.push(`grant ${p.toLowerCase()} on ${T} to ${R}`);
+        continue;
+      }
+      if (tableWide) {
+        // revoking the table-wide privilege revokes the column privileges too
+        out.push(`revoke ${p.toLowerCase()} on ${T} from ${R}`);
+        if (w.size) out.push(`grant ${p.toLowerCase()} (${list(all.filter((c) => w.has(c)))}) on ${T} to ${R}`);
+        continue;
+      }
+      const off = all.filter((c) => have.has(c) && !w.has(c));
+      const on = all.filter((c) => w.has(c) && !have.has(c));
+      if (off.length) out.push(`revoke ${p.toLowerCase()} (${list(off)}) on ${T} from ${R}`);
+      if (on.length) out.push(`grant ${p.toLowerCase()} (${list(on)}) on ${T} to ${R}`);
+    }
+  }
+  const v = def.view;
+  const masked = maskedColumns(v);
+  const readers = viewReaders(def);
+  if (!v.enabled) {
+    if (cur.view) out.push(`drop view ${ident(cur.schema)}.${ident(cur.view.name)}`);
+    else if (masked.length) warnings.push('Masks only apply through the masking view: switch it on.');
+    return { statements: out, warnings };
+  }
+  const config: MaskConfig = { table: cur.table, roles: v.roles, cols: Object.fromEntries(masked.map((c) => [c, v.cols[c]])) };
+  const V = `${ident(cur.schema)}.${ident(v.name)}`;
+  const M = ident(cur.maskRole);
+  const sameView = cur.view && cur.view.name === v.name && cur.view.columns.join('\0') === all.join('\0') && configComment(cur.view.config) === configComment(config);
+  const newMembers = readers.filter((r) => r !== 'PUBLIC' && !cur.maskMembers.includes(r));
+  if (!sameView || newMembers.length || !cur.maskRoleExists) {
+    if (cur.view) out.push(`drop view ${ident(cur.schema)}.${ident(cur.view.name)}`);
+    else out.push(`drop view if exists ${V}`);
+    if (!cur.maskRoleExists) {
+      out.push(`create role ${M} nologin`);
+      out.push(`grant ${M} to current_user`);
+    }
+    out.push(`grant usage on schema ${ident(cur.schema)} to ${M}`);
+    out.push(`grant select on ${T} to ${M}`);
+    // a member of the readers: their policies (to <role>) and the functions those policies call apply in the view
+    for (const r of newMembers) out.push(`grant ${ident(r)} to ${M}`);
+    out.push(`create view ${V} with (security_barrier) as\nselect ${all.map((c) => columnSql(c, v.roles, v.cols[c])).join(',\n       ')}\n  from ${T} t`);
+    out.push(`alter view ${V} owner to ${M}`);
+    out.push(`comment on view ${V} is ${lit(configComment(config))}`);
+    for (const r of readers) out.push(`grant select on ${V} to ${roleIdent(r)}`);
+    // the view runs as the masking role: it must stay under row level security
+    out.push(`do $check$ begin
+  if exists (select from pg_roles r where r.rolname = ${lit(cur.maskRole)}
+              and (r.rolsuper or r.rolbypassrls or pg_has_role(r.oid, ${lit(cur.owner)}::regrole, 'USAGE'))) then
+    raise exception 'the masking role ${cur.maskRole.replace(/'/g, "''")} would bypass row level security on ${cur.schema.replace(/'/g, "''")}.${cur.table.replace(/'/g, "''")}';
+  end if;
+end $check$`);
+  }
+  for (const c of masked) {
+    const raw = def.grants.filter((g) => g.select.includes(c)).map((g) => g.role);
+    if (raw.length) warnings.push(`${raw.join(', ')} can still read ${cur.table}.${c} on the table itself: the mask holds only where ${raw.length > 1 ? 'they read' : 'it reads'} ${v.name}. Untick "read" of ${c} to make it hold everywhere.`);
+  }
+  if (masked.length && !readers.length) warnings.push('No database role reads the table, so no role gets the masking view.');
+  return { statements: out, warnings };
+}

package/src/mail/mail.ts

@@ -12,7 +12,8 @@
 import pg from 'pg';
 import { owner } from '../db.ts';
 import { decryptSecret } from '../secrets.ts';
-import { deliver, MailError, type OutgoingMail, type Provider, type ServiceSettings } from './providers.ts';
+import { mailHostAddress, scopeForWorkspace } from '../network-acl.ts';
+import { deliver, MailError, verifyConnection, type OutgoingMail, type Provider, type ServiceSettings } from './providers.ts';
 
 export interface MailService {
   id: number;
@@ -23,6 +24,8 @@ export interface MailService {
   secret_enc: string | null;
   senders: string[];
   enabled: boolean;
+  /** (sprint 118) a workspace's own service (its administrators manage it); null: the installation's */
+  workspace_id?: number | null;
 }
 
 const PER_PASS = 20;
@@ -37,7 +40,7 @@ export function senderAllowed(senders: string[], from: string) {
 }
 
 /** Send one message through a service now (the worker, and the builder's test). Returns the provider's id. */
-export async function sendWith(service: MailService, m: OutgoingMail) {
+export async function sendWith(service: MailService, m: OutgoingMail, appId: number | null = null) {
   if (!service.enabled) throw new MailError(`Mail service ${service.name} is disabled.`, false);
   if (!senderAllowed(service.senders, m.from)) throw new MailError(`Mail service ${service.name} may not send as ${m.from}.`, false);
   let secret: string | null = null;
@@ -46,7 +49,35 @@ export async function sendWith(service: MailService, m: OutgoingMail) {
   } catch (e) {
     throw new MailError(`The secret of mail service ${service.name} can't be read: ${(e as Error).message}`, false);
   }
-  return deliver(service.provider, service.settings ?? {}, secret, m);
+  return deliver(service.provider, await serviceSettings(service, appId), secret, m);
+}
+
+/**
+ * (sprint 118) The settings a service is used with. A workspace's own service has no base URL or
+ * token URL of its own (the providers' own APIs only), and its SMTP host must be on the
+ * installation's allow-list and the workspace's network access list, and resolve to a public
+ * address (unless PGKILN_REST_PRIVATE_HOSTS lists it): the connection goes to the address checked here.
+ */
+export async function serviceSettings(service: Pick<MailService, 'name' | 'provider' | 'settings' | 'workspace_id'>, appId: number | null = null): Promise<ServiceSettings> {
+  const settings = service.settings ?? {};
+  if (!service.workspace_id) return settings;
+  if (settings.base_url) throw new MailError(`Mail service ${service.name} belongs to a workspace: it uses the provider's own API (no base URL).`, false);
+  if (settings.token_url) throw new MailError(`Mail service ${service.name} belongs to a workspace: OAuth2 uses Microsoft Entra of the tenant (no token URL).`, false);
+  if (service.provider !== 'smtp') return settings;
+  const scope = await scopeForWorkspace(service.workspace_id, `mail service ${service.name}`);
+  if (!scope) throw new MailError(`Mail service ${service.name}: its workspace is gone.`, false);
+  const port = settings.port ?? (settings.security === 'tls' ? 465 : 587);
+  try {
+    const { address, servername } = await mailHostAddress({ ...scope, appId }, String(settings.host ?? ''), port);
+    return { ...settings, host: address, port, servername: servername ?? settings.host };
+  } catch (e) {
+    throw new MailError((e as Error).message, false);
+  }
+}
+
+/** (sprint 118) The connection check of a service (a workspace's with the checks of serviceSettings). */
+export async function verifyService(service: Pick<MailService, 'name' | 'provider' | 'settings' | 'workspace_id'>, secret: string | null) {
+  return verifyConnection(service.provider, await serviceSettings(service), secret);
 }
 
 interface Claimed {
@@ -64,8 +95,11 @@ interface Claimed {
 }
 
 async function sendOne(m: Claimed) {
-  const service = await owner.one<MailService>(
-    `select s.* from meta.app_mail_service x join meta.mail_service s on s.id = x.service_id where x.app_id = $1`, [m.app_id]);
+  // the application's service, else (sprint 118) its workspace's own
+  const service = await owner.one<MailService>(`select s.* from meta.mail_service s where s.id = meta.mail_service_for_app($1)`, [m.app_id]);
+  const t0 = performance.now();
+  // (sprint 118) when the last attempt ended, how long the provider took (Administration → Mail queue)
+  const timing = () => [Math.round(performance.now() - t0), service?.provider ?? null] as const;
   try {
     if (!service) throw new MailError('The application has no mail service any more.', false);
     const attachments = (await owner.query<{ filename: string; mime: string; content: Buffer }>(
@@ -73,16 +107,21 @@ async function sendOne(m: Claimed) {
     const id = await sendWith(service, {
       from: m.from_address, to: m.to_addresses, cc: m.cc_addresses, bcc: m.bcc_addresses, replyTo: m.reply_to,
       subject: m.subject, text: m.body_text, html: m.body_html, attachments,
-    });
-    await owner.query(`update meta.mail_queue set status = 'sent', sent_at = now(), provider_id = $2, service = $3, message = null where id = $1`,
-      [m.id, id ? String(id).slice(0, 500) : null, service.name]);
+    }, m.app_id);
+    const [ms, provider] = timing();
+    await owner.query(`update meta.mail_queue set status = 'sent', sent_at = now(), provider_id = $2, service = $3, message = null,
+                              last_attempt_at = now(), duration_ms = $4, provider = $5 where id = $1`,
+      [m.id, id ? String(id).slice(0, 500) : null, service.name, ms, provider]);
   } catch (e) {
     const retry = e instanceof MailError ? e.retry : true;
     const message = (e as Error).message.slice(0, 2000);
+    const [ms, provider] = timing();
     if (retry && m.attempts < ATTEMPTS)
-      await owner.query(`update meta.mail_queue set status = 'queued', not_before = now() + make_interval(mins => $2), message = $3, service = $4 where id = $1`,
-        [m.id, 4 ** (m.attempts - 1), message, service?.name ?? null]);
-    else await owner.query(`update meta.mail_queue set status = 'error', message = $2, service = $3 where id = $1`, [m.id, message, service?.name ?? null]);
+      await owner.query(`update meta.mail_queue set status = 'queued', not_before = now() + make_interval(mins => $2), message = $3, service = $4,
+                                last_attempt_at = now(), duration_ms = $5, provider = $6 where id = $1`,
+        [m.id, 4 ** (m.attempts - 1), message, service?.name ?? null, ms, provider]);
+    else await owner.query(`update meta.mail_queue set status = 'error', message = $2, service = $3, last_attempt_at = now(), duration_ms = $4, provider = $5 where id = $1`,
+      [m.id, message, service?.name ?? null, ms, provider]);
   }
 }
 

package/src/mail/providers.ts

@@ -77,6 +77,8 @@ export interface ServiceSettings {
   // the API's address instead of the provider's own (administrators only; a proxy, or tests)
   base_url?: string;
   default_from?: string;
+  /** (sprint 118) not stored: the host name for TLS when `host` is the address checked for a workspace's service */
+  servername?: string;
 }
 
 export class MailError extends Error {
@@ -203,6 +205,7 @@ async function smtp(m: OutgoingMail, s: ServiceSettings, secret: string | null)
     };
   const transport = nodemailer.createTransport({
     host: s.host,
+    ...(s.servername ? { servername: s.servername } : {}),
     port: s.port ?? (security === 'tls' ? 465 : 587),
     secure: security === 'tls',
     requireTLS: security === 'starttls',
@@ -387,7 +390,7 @@ export async function verifyConnection(provider: Provider, s: ServiceSettings, s
       const security = s.security ?? 'starttls';
       const auth = s.auth ?? 'password';
       const transport = nodemailer.createTransport({
-        host: s.host, port: s.port ?? (security === 'tls' ? 465 : 587), secure: security === 'tls', requireTLS: security === 'starttls', ignoreTLS: security === 'none',
+        host: s.host, ...(s.servername ? { servername: s.servername } : {}), port: s.port ?? (security === 'tls' ? 465 : 587), secure: security === 'tls', requireTLS: security === 'starttls', ignoreTLS: security === 'none',
         auth: (auth === 'password' ? { user: s.username, pass: secret ?? '' }
           : auth === 'oauth2' ? { type: 'OAuth2', user: s.username, accessToken: await clientCredentialsToken(entraTokenUrl(s), s.client_id ?? '', secret ?? '', s.scope || 'https://outlook.office365.com/.default') }
           : undefined) as never,
@@ -397,11 +400,11 @@ export async function verifyConnection(provider: Provider, s: ServiceSettings, s
         await transport.verify();
       } catch (e) {
         const err = e as { response?: string; message: string; code?: string };
-        throw new MailError(`The SMTP server ${s.host}: ${(err.response ?? err.message).slice(0, 500)}`, false);
+        throw new MailError(`The SMTP server ${s.servername ?? s.host}: ${(err.response ?? err.message).slice(0, 500)}`, false);
       } finally {
         transport.close();
       }
-      return `Connected to ${s.host}:${s.port ?? (security === 'tls' ? 465 : 587)}${security === 'none' ? '' : ` with ${security === 'tls' ? 'TLS' : 'STARTTLS'}`}${
+      return `Connected to ${s.servername ?? s.host}:${s.port ?? (security === 'tls' ? 465 : 587)}${security === 'none' ? '' : ` with ${security === 'tls' ? 'TLS' : 'STARTTLS'}`}${
         auth === 'none' ? '' : ` and signed in as ${s.username}${auth === 'oauth2' ? ' with OAuth2' : ''}`}.`;
     }
     case 'graph':

package/src/metadata.ts

@@ -123,6 +123,8 @@ export interface App {
     base?: string;
     /** (0.29) the accent and header colours in dark mode */
     accent_dark?: string; header_dark?: string;
+    /** (sprint 117) the navigation appearance (Pillar Light / Dark) and the header pillar strip's colours */
+    appearance?: string; strip?: string; strip_dark?: string;
   };
   /** primary language, translated languages, and how the language is chosen */
   language: string;