shutro-erp 0.3.2 → 0.3.3

package/dist/payment/stripe.d.ts

@@ -0,0 +1,15 @@
+import type { PaymentAdapter } from './providers.js';
+export interface StripeOptions {
+    readonly secretKey?: string | undefined;
+    /** The API's base (default `https://api.stripe.com/v1`). */
+    readonly baseUrl?: string | undefined;
+    /** How old a signed event may be, in seconds (default 300). */
+    readonly tolerance?: number;
+    /** The HTTP client (tests). */
+    readonly fetch?: typeof fetch;
+    /** The clock (tests). */
+    readonly now?: () => number;
+}
+export declare function stripeAdapter(options?: StripeOptions): PaymentAdapter;
+/** Stripe with its key from the environment, read on first use. */
+export declare function stripeFromEnvironment(env?: NodeJS.ProcessEnv): PaymentAdapter;

package/dist/payment/stripe.js

@@ -0,0 +1,182 @@
+/**
+ * The Stripe adapter (RFC 0017 §5.5), on Checkout Sessions: a session per transaction (`client_reference_id` and
+ * `metadata.reference` = its reference, one line of the invoice's amount in subunits) whose page the customer pays
+ * on, back to the return route. Stripe's webhook is set up in its dashboard with the provider's endpoint URL; Stripe
+ * gives the signing secret (`whsec_…`), which goes into **the endpoint's Secret**. `Stripe-Signature`
+ * (`t=…,v1=…`: HMAC-SHA256 hex of `"<t>.<raw body>"`) is checked with it, and old timestamps are refused (5 minutes)
+ * against replays; the event's `id` makes deliveries idempotent. Returns fetch the session from Stripe.
+ *
+ * Credentials come from the environment, never from records: `SHUTRO_ERP_STRIPE_SECRET_KEY`. Test keys
+ * (`sk_test_…`, `rk_test_…`) serve providers in test mode, live keys live ones.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { fromSubunits, toSubunits } from './money.js';
+const text = (v) => (v === undefined || v === null ? '' : String(v));
+/** What a Checkout Session says of its payment. */
+function sessionResult(reference, session, kind) {
+    const theirs = text(session['client_reference_id']) ||
+        text(session['metadata']?.['reference']);
+    if (theirs !== reference)
+        return null;
+    const currency = text(session['currency']).toUpperCase();
+    const intent = session['payment_intent'];
+    const providerReference = (typeof intent === 'string' ? intent : text(intent?.['id'])) ||
+        text(session['id']) ||
+        null;
+    // A delayed method (a bank debit) that did not go through.
+    if (kind === 'checkout.session.async_payment_failed')
+        return {
+            reference,
+            status: 'failed',
+            providerReference,
+            error: 'The payment failed at Stripe.',
+        };
+    if (text(session['payment_status']) === 'paid')
+        return {
+            reference,
+            status: 'done',
+            providerReference,
+            amount: fromSubunits(Number(session['amount_total'] ?? 0), currency),
+            currency,
+        };
+    if (text(session['status']) === 'expired' || kind === 'checkout.session.expired')
+        return { reference, status: 'cancelled', providerReference };
+    return { reference, status: 'pending', providerReference };
+}
+/** Stripe's form encoding of nested parameters (`line_items[0][price_data][currency]=bdt`). */
+function form(params, prefix = '', out = new URLSearchParams()) {
+    for (const [key, value] of Object.entries(params)) {
+        const name = prefix === '' ? key : `${prefix}[${key}]`;
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value))
+            value.forEach((v, i) => {
+                if (typeof v === 'object' && v !== null)
+                    form(v, `${name}[${i}]`, out);
+                else
+                    out.append(`${name}[${i}]`, String(v));
+            });
+        else if (typeof value === 'object')
+            form(value, name, out);
+        else
+            out.append(name, String(value));
+    }
+    return out;
+}
+export function stripeAdapter(options = {}) {
+    const key = options.secretKey ?? '';
+    const base = (options.baseUrl || 'https://api.stripe.com/v1').replace(/\/$/, '');
+    const http = options.fetch ?? fetch;
+    const tolerance = options.tolerance ?? 300;
+    const now = options.now ?? (() => Date.now());
+    const ready = /^(sk|rk)_(test|live)_/.test(key);
+    const call = async (method, path, params) => {
+        if (!ready)
+            throw new Error('Stripe is not configured: set SHUTRO_ERP_STRIPE_SECRET_KEY.');
+        const res = await http(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${key}`,
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            ...(params === undefined ? {} : { body: form(params) }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        const answer = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const error = (answer['error'] ?? {});
+            throw new Error(`Stripe answered ${res.status}: ${text(error['message']) || 'no detail'}.`);
+        }
+        return answer;
+    };
+    const session = (id) => call('GET', `/checkout/sessions/${encodeURIComponent(id)}`);
+    return {
+        code: 'stripe',
+        configured: (mode) => ready && key.includes(mode === 'test' ? '_test_' : '_live_'),
+        async createPayment(request) {
+            const made = await call('POST', '/checkout/sessions', {
+                mode: 'payment',
+                client_reference_id: request.reference,
+                success_url: request.returnUrl,
+                cancel_url: request.returnUrl,
+                ...(request.customer.email === null ? {} : { customer_email: request.customer.email }),
+                line_items: [
+                    {
+                        quantity: 1,
+                        price_data: {
+                            currency: request.currency.toLowerCase(),
+                            unit_amount: toSubunits(request.amount, request.currency),
+                            product_data: { name: request.description },
+                        },
+                    },
+                ],
+                metadata: { reference: request.reference },
+                payment_intent_data: { metadata: { reference: request.reference } },
+            });
+            const id = text(made['id']);
+            const page = text(made['url']);
+            if (id === '' || page === '')
+                throw new Error('Stripe made no Checkout Session.');
+            return { redirectUrl: page, providerReference: id };
+        },
+        verifyCallback(call, secret) {
+            const header = call.headers['stripe-signature'] ?? '';
+            const parts = header.split(',').map((p) => p.split('='));
+            const t = Number(parts.find(([k]) => k === 't')?.[1]);
+            if (!Number.isFinite(t) || Math.abs(now() / 1000 - t) > tolerance)
+                return null;
+            const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${call.body}`).digest('hex'));
+            const genuine = parts
+                .filter(([k]) => k === 'v1')
+                .some(([, v]) => {
+                const given = Buffer.from(v ?? '');
+                return given.length === expected.length && timingSafeEqual(given, expected);
+            });
+            if (!genuine)
+                return null;
+            const id = text(call.json?.['id']);
+            return id !== '' ? id : null;
+        },
+        readCallback(call) {
+            const event = call.json;
+            const kind = text(event?.['type']);
+            if (!kind.startsWith('checkout.session.'))
+                return null;
+            const object = (event?.['data']?.['object'] ?? null);
+            if (object === null)
+                return null;
+            const reference = text(object['client_reference_id']) ||
+                text(object['metadata']?.['reference']);
+            const result = sessionResult(reference, object, kind);
+            return result === null || result.status === 'pending' ? null : result;
+        },
+        async returned({ reference, providerReference }) {
+            if (providerReference === null || providerReference === '')
+                return null;
+            const result = sessionResult(reference, await session(providerReference));
+            return result?.status === 'pending' ? null : result;
+        },
+        async status(reference, _mode, providerReference) {
+            if (!ready || providerReference === null || providerReference === '')
+                return null;
+            return sessionResult(reference, await session(providerReference));
+        },
+    };
+}
+/** Stripe with its key from the environment, read on first use. */
+export function stripeFromEnvironment(env = process.env) {
+    let made;
+    const real = () => (made ??= stripeAdapter({
+        secretKey: env['KOSH_STRIPE_SECRET_KEY'],
+        baseUrl: env['KOSH_STRIPE_BASE_URL'],
+    }));
+    return {
+        code: 'stripe',
+        configured: (mode) => real().configured(mode),
+        createPayment: (request) => real().createPayment(request),
+        verifyCallback: (call, secret) => real().verifyCallback(call, secret),
+        readCallback: (call) => real().readCallback(call),
+        returned: (input) => real().returned?.(input) ?? Promise.resolve(null),
+        status: (reference, mode, providerReference) => real().status(reference, mode, providerReference),
+    };
+}

package/dist/permissions/admin.d.ts

@@ -9,5 +9,8 @@
  * Approval policies are data: administrators edit `approval.policy` / `approval.level` through the generated API.
  */
 import { type ModuleContext } from '../server/index.js';
+import type { Env } from '../server/orm.js';
+/** Refuses non-administrators (or, with `permission`, users without it). */
+export declare function requireAdministrator(env: Env, permission?: string): void;
 /** Registers `/api/v1/admin/*`. */
 export declare function registerAdminApi(context: ModuleContext): void;

package/dist/permissions/admin.js

@@ -43,7 +43,7 @@ function idParam(request, key = 'id') {
     return id;
 }
 /** Refuses non-administrators (or, with `permission`, users without it). */
-function requireAdministrator(env, permission) {
+export function requireAdministrator(env, permission) {
     if (env.administrator)
         return;
     if (permission !== undefined && env.access.has(permission))
@@ -99,6 +99,10 @@ export function registerAdminApi(context) {
             params: [],
         });
         const admins = env.access.administratorGroups();
+        // How many people hold each role (administrators read the assignments).
+        const holders = new Map();
+        for (const a of await find(env, 'auth.user_group', {}, ['user', 'group']))
+            holders.set(String(a['group']), (holders.get(String(a['group'])) ?? new Set()).add(a['user']));
         const levelsOf = (implies) => {
             const closure = reg.security.closure(implies.filter((c) => reg.security.groups.has(c)));
             return [...loaded.accessLevels.entries()]
@@ -114,6 +118,7 @@ export function registerAdminApi(context) {
                     administrator: admins.has(g.code),
                     builtIn: true,
                     accessLevels: levelsOf(g.implies),
+                    holders: holders.get(g.code)?.size ?? 0,
                 })),
                 ...runtime.map((r) => ({
                     code: r.code,
@@ -122,6 +127,7 @@ export function registerAdminApi(context) {
                     administrator: admins.has(r.code),
                     builtIn: false,
                     accessLevels: levelsOf(r.implies),
+                    holders: holders.get(r.code)?.size ?? 0,
                 })),
             ],
         };
@@ -342,6 +348,7 @@ export function registerAdminApi(context) {
                 models: Object.fromEntries(models.map((name) => [
                     name,
                     {
+                        label: reg.get(name).model.label ?? name,
                         perms: PERMS.filter((p) => env.access.can(name, p)),
                         hiddenFields: Object.keys(reg.get(name).model.fields).filter((k) => !env.access.canField(name, k, 'read')),
                         readonlyFields: Object.keys(reg.get(name).model.fields).filter((k) => env.access.canField(name, k, 'read') &&
@@ -351,25 +358,67 @@ export function registerAdminApi(context) {
                 permissions: [...reg.security.permissions.keys()]
                     .filter((code) => env.access.has(code))
                     .sort(),
+                /** The permissions' names, for screens. */
+                permissionLabels: Object.fromEntries([...reg.security.permissions.values()].map((p) => [p.code, p.label ?? p.code])),
             };
         });
     });
     const hidden = new Set(loaded.modules.flatMap((m) => m.privateModels ?? []));
     const privateModel = (name) => hidden.has(name);
     // ------------------------------------------------------------------------------------------- audit log
-    app.get('/api/v1/admin/audit', async (request) => {
+    // Filters (RFC 0019 §3.5): `kind` (`auth.` for a family), `actor` (a user id), `model` and `record` (the target),
+    // `from` / `to` (ISO dates, `to` inclusive of its day), `q` (words of the summary), `before` (an id: the next page);
+    // `format=csv` downloads the page as CSV — an export, itself audited.
+    app.get('/api/v1/admin/audit', async (request, reply) => {
         const q = (request.query ?? {});
-        const limit = q.limit === undefined ? 100 : Number(q.limit);
+        const limit = q['limit'] === undefined ? 100 : Number(q['limit']);
         if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
             throw bad('limit must be 1–1000.');
-        return request.env(async (env) => {
+        const where = {};
+        const text = (key) => typeof q[key] === 'string' && q[key] !== '' ? q[key] : undefined;
+        const id = (key) => {
+            const v = text(key);
+            if (v === undefined)
+                return undefined;
+            const n = Number(v);
+            if (!Number.isSafeInteger(n) || n <= 0)
+                throw bad(`${key} is a positive integer.`);
+            return n;
+        };
+        const date = (key) => {
+            const v = text(key);
+            if (v === undefined)
+                return undefined;
+            const d = new Date(v);
+            if (Number.isNaN(d.getTime()))
+                throw bad(`${key} is an ISO date.`);
+            return d;
+        };
+        const kind = text('kind');
+        if (kind !== undefined)
+            where['kind'] = kind.endsWith('.') ? { like: `${kind}%` } : kind;
+        if (id('actor') !== undefined)
+            where['actor'] = id('actor');
+        if (text('model') !== undefined)
+            where['targetModel'] = text('model');
+        if (id('record') !== undefined)
+            where['targetId'] = id('record');
+        if (text('q') !== undefined)
+            where['summary'] = { ilike: `%${text('q')}%` };
+        const from = date('from');
+        const to = date('to');
+        if (from !== undefined || to !== undefined)
+            where['createdAt'] = {
+                ...(from === undefined ? {} : { gte: from }),
+                // `to` is a day: everything before the next one.
+                ...(to === undefined ? {} : { lt: new Date(to.getTime() + 86_400_000) }),
+            };
+        if (id('before') !== undefined)
+            where['id'] = { lt: id('before') };
+        const csv = q['format'] === 'csv';
+        const events = await request.env(async (env) => {
             requireAdministrator(env, 'permissions.view_audit');
             return env.asSuperuser({ reason: 'read audit log' }, async (su) => {
-                const where = {};
-                if (typeof q.kind === 'string' && q.kind !== '')
-                    where['kind'] = q.kind.endsWith('.') ? { like: `${q.kind}%` } : q.kind;
-                if (q.before !== undefined)
-                    where['id'] = { lt: Number(q.before) };
                 const set = await ref(su, 'audit.event').search({ where, order: ['id desc'], limit });
                 const keys = [
                     'kind',
@@ -382,8 +431,57 @@ export function registerAdminApi(context) {
                     'ip',
                     'createdAt',
                 ];
-                return { events: set.length === 0 ? [] : (await set.load(keys)).read(keys) };
+                const found = set.length === 0 ? [] : (await set.load(keys)).read(['id', ...keys]);
+                const actors = [
+                    ...new Set(found.map((e) => e['actor']).filter((a) => typeof a === 'number')),
+                ];
+                const names = new Map(actors.length === 0
+                    ? []
+                    : (await // Deactivated people keep their name in the log.
+                     (await ref(su.withFlags({ activeTest: false }), 'res.users').search({
+                        where: { id: { in: actors } },
+                    })).load(['name']))
+                        .read(['id', 'name'])
+                        .map((u) => [u['id'], String(u['name'])]));
+                if (csv)
+                    await audit(env, {
+                        kind: 'data.export',
+                        summary: `Exported ${found.length} audit event(s).`,
+                        targetModel: 'audit.event',
+                        details: { filters: where },
+                        ip: request.ip,
+                    });
+                return found.map((e) => ({
+                    ...e,
+                    actorName: typeof e['actor'] === 'number' ? (names.get(e['actor']) ?? null) : null,
+                }));
             });
         }, { write: true }); // the system read of the log is itself audited
+        if (!csv)
+            return { events };
+        const cell = (v) => {
+            const s = v === null || v === undefined ? '' : v instanceof Date ? v.toISOString() : String(v);
+            // Quoted, and never read as a formula by a spreadsheet.
+            return `"${(/^[=+\-@]/.test(s) ? `'${s}` : s).replaceAll('"', '""')}"`;
+        };
+        const columns = [
+            'id',
+            'createdAt',
+            'kind',
+            'actorName',
+            'summary',
+            'targetModel',
+            'targetId',
+            'ip',
+        ];
+        const lines = [
+            columns.join(','),
+            ...events.map((e) => columns.map((c) => cell(e[c])).join(',')),
+        ];
+        // A byte-order mark so spreadsheets read UTF-8 (Bangla names).
+        return reply
+            .header('content-type', 'text/csv; charset=utf-8')
+            .header('content-disposition', 'attachment; filename="audit-log.csv"')
+            .send(`${lines.join('\r\n')}\r\n`);
     });
 }

package/dist/permissions/index.d.ts

@@ -8,6 +8,7 @@ import { defineModule } from '../modules-sdk/index.js';
 export { registerAdminApi } from './admin.js';
 export { type ApprovalRequestInfo, approvalGuard, approvalState, decide, inbox, installApprovalPolicies, requestApprovals, requestsOf, } from './approvals.js';
 export { permissionsShutro } from './models.js';
+export { registerRoleRoutes } from './roles.js';
 export { registerApprovalRoutes } from './routes.js';
 /** Package identity. */
 export declare const PACKAGE: {

package/dist/permissions/index.js

@@ -9,10 +9,12 @@ import { base } from '../server/index.js';
 import { registerAdminApi } from './admin.js';
 import { installApprovalPolicies } from './approvals.js';
 import { permissionsShutro } from './models.js';
+import { registerRoleRoutes } from './roles.js';
 import { registerApprovalRoutes } from './routes.js';
 export { registerAdminApi } from './admin.js';
 export { approvalGuard, approvalState, decide, inbox, installApprovalPolicies, requestApprovals, requestsOf, } from './approvals.js';
 export { permissionsShutro } from './models.js';
+export { registerRoleRoutes } from './roles.js';
 export { registerApprovalRoutes } from './routes.js';
 /** Package identity. */
 export const PACKAGE = Object.freeze({
@@ -36,6 +38,7 @@ export const permissions = defineModule({
     },
     routes: (context) => {
         registerAdminApi(context);
+        registerRoleRoutes(context);
         registerApprovalRoutes(context);
     },
 });

package/dist/permissions/roles.d.ts

@@ -0,0 +1,2 @@
+import { type ModuleContext } from '../server/index.js';
+export declare function registerRoleRoutes(context: ModuleContext): void;

package/dist/permissions/roles.js

@@ -0,0 +1,236 @@
+import { HttpProblem } from '../server/index.js';
+import { requireAdministrator } from './admin.js';
+const PERMS = ['read', 'write', 'create', 'unlink', 'export', 'import'];
+const find = async (env, model, where, keys) => {
+    const set = (await env.model(model).search({ where, order: ['id asc'] }));
+    return set.length === 0 ? [] : (await set.load(keys)).read(['id', ...keys]);
+};
+const bad = (detail) => new HttpProblem(400, 'invalid-body', 'Invalid request', detail);
+export function registerRoleRoutes(context) {
+    const { app, registry } = context;
+    const reg = registry.registry;
+    const loaded = registry.loaded;
+    const modules = loaded.modules;
+    const hidden = new Set(modules.flatMap((m) => m.privateModels ?? []));
+    const appOf = new Map(modules.map((m) => [m.name, m.app?.label ?? null]));
+    /** Every group a set of roles amounts to: declared groups' closure, runtime roles followed through. */
+    const closureOf = (codes, runtime) => {
+        const roles = new Map(runtime.roles.map((r) => [r.code, r]));
+        const seen = new Set();
+        const queue = [...codes];
+        while (queue.length > 0) {
+            const code = queue.pop();
+            if (seen.has(code))
+                continue;
+            seen.add(code);
+            for (const next of roles.get(code)?.implies ?? [])
+                queue.push(next);
+        }
+        return new Set([
+            ...seen,
+            ...reg.security.closure([...seen].filter((c) => reg.security.groups.has(c))),
+        ]);
+    };
+    /** What a set of groups grants: per model the permissions, and the feature permissions. */
+    const grants = (groups, runtime, except) => {
+        const models = new Map();
+        for (const [name, model] of reg.models) {
+            const access = (model.model.access ?? {});
+            const perms = new Set();
+            for (const g of groups)
+                for (const p of access[g] ?? [])
+                    perms.add(p);
+            if (perms.size > 0)
+                models.set(name, perms);
+        }
+        for (const a of runtime.access)
+            if (groups.has(a.role) && a.role !== except)
+                for (const p of a.perms) {
+                    const set = models.get(a.model) ?? new Set();
+                    set.add(p);
+                    models.set(a.model, set);
+                }
+        const permissions = new Set();
+        for (const p of reg.security.permissions.values())
+            if (p.groups.some((g) => groups.has(g)))
+                permissions.add(p.code);
+        for (const g of runtime.permissions)
+            if (groups.has(g.role) && g.role !== except)
+                permissions.add(g.permission);
+        const levels = new Set([...loaded.accessLevels.entries()]
+            .filter(([, level]) => level.groups.length > 0 && level.groups.every((g) => groups.has(g)))
+            .map(([code]) => code));
+        return { models, permissions, levels };
+    };
+    const levelLabel = (code) => {
+        const level = loaded.accessLevels.get(code);
+        return level === undefined
+            ? code
+            : `${appOf.get(level.module) ?? level.module} · ${level.label}`;
+    };
+    const permissionLabel = (code) => reg.security.permissions.get(code)?.label ?? code;
+    /** The role, whether declared in code or made at runtime. */
+    const roleOf = (code, runtime) => {
+        const declared = reg.security.groups.get(code);
+        if (declared !== undefined)
+            return {
+                code,
+                label: declared.label ?? code,
+                implies: [...(declared.implies ?? [])],
+                builtIn: true,
+            };
+        const made = runtime.roles.find((r) => r.code === code);
+        if (made === undefined)
+            throw new HttpProblem(404, 'missing-record', 'Not found', `There is no role '${code}'.`);
+        return { code, label: made.label, implies: [...made.implies], builtIn: false };
+    };
+    const holdersOf = async (env, code) => env.asSuperuser({ reason: 'role holders' }, async (su) => {
+        const assigned = await find(su, 'auth.user_group', { group: code }, ['user']);
+        const ids = [...new Set(assigned.map((a) => a['user']))];
+        if (ids.length === 0)
+            return [];
+        return (await find(su, 'res.users', { id: { in: ids } }, ['name', 'login'])).map((u) => ({
+            id: u['id'],
+            name: String(u['name']),
+            login: String(u['login']),
+        }));
+    });
+    const codeParam = (request) => String(request.params['code'] ?? '');
+    app.get('/api/v1/admin/roles/:code', async (request) => {
+        const code = codeParam(request);
+        return request.env(async (env) => {
+            requireAdministrator(env);
+            const runtime = await env.securityAdmin.describe();
+            const role = roleOf(code, runtime);
+            const closure = closureOf([code], runtime);
+            // Locked: what code and the included roles give; own: this role's runtime grants.
+            const locked = grants(closure, runtime, code);
+            const own = new Map(runtime.access.filter((a) => a.role === code).map((a) => [a.model, [...a.perms]]));
+            const ownPermissions = runtime.permissions
+                .filter((p) => p.role === code)
+                .map((p) => p.permission);
+            return {
+                ...role,
+                administrator: env.access.administratorGroups().has(code),
+                accessLevels: [...grants(closureOf(role.implies, runtime), runtime).levels],
+                holders: await holdersOf(env, code),
+                models: [...reg.models]
+                    .filter(([name]) => !hidden.has(name) && !name.startsWith('shutro.'))
+                    .map(([name, model]) => ({
+                    name,
+                    label: model.model.label ?? name,
+                    app: appOf.get(model.module) ?? null,
+                    locked: [...(locked.models.get(name) ?? [])],
+                    own: own.get(name) ?? [],
+                }))
+                    // Apps first (by name), technical models last.
+                    .sort((a, b) => Number(a.app === null) - Number(b.app === null) ||
+                    (a.app ?? '').localeCompare(b.app ?? '') ||
+                    a.label.localeCompare(b.label)),
+                permissions: [...reg.security.permissions.values()].map((p) => ({
+                    code: p.code,
+                    label: p.label ?? p.code,
+                    locked: locked.permissions.has(p.code),
+                    own: ownPermissions.includes(p.code),
+                })),
+                rules: runtime.rules.filter((r) => r.role === code),
+                fields: runtime.fields.filter((f) => f.read.includes(code) || f.write.includes(code)),
+            };
+        }, { write: true });
+    });
+    app.post('/api/v1/admin/roles/:code/preview', async (request) => {
+        const code = codeParam(request);
+        const body = (request.body ?? {});
+        const list = (v, what) => {
+            if (v === undefined)
+                return undefined;
+            if (!Array.isArray(v) || v.some((x) => typeof x !== 'string'))
+                throw bad(`${what} is a list of codes.`);
+            return v;
+        };
+        const levels = list(body['accessLevels'], 'accessLevels');
+        const implies = list(body['implies'], 'implies');
+        const permissions = list(body['permissions'], 'permissions');
+        const access = body['access'];
+        if (access !== undefined &&
+            (typeof access !== 'object' || access === null || Array.isArray(access)))
+            throw bad('access is { model: [permissions] }.');
+        return request.env(async (env) => {
+            requireAdministrator(env);
+            const runtime = await env.securityAdmin.describe();
+            const role = roleOf(code, runtime);
+            // The role's proposed state, as a runtime overlay of itself.
+            const levelGroups = (levels ?? []).flatMap((l) => {
+                const level = loaded.accessLevels.get(l);
+                if (level === undefined)
+                    throw bad(`'${l}' is not an access level.`);
+                return [...level.groups];
+            });
+            const proposedImplies = levels === undefined && implies === undefined
+                ? role.implies
+                : [...new Set([...levelGroups, ...(implies ?? [])])];
+            const ownAccess = (access ??
+                Object.fromEntries(runtime.access.filter((a) => a.role === code).map((a) => [a.model, a.perms])));
+            const proposed = {
+                ...runtime,
+                roles: role.builtIn
+                    ? runtime.roles
+                    : runtime.roles.map((r) => (r.code === code ? { ...r, implies: proposedImplies } : r)),
+                access: [
+                    ...runtime.access.filter((a) => a.role !== code),
+                    ...Object.entries(ownAccess).map(([model, perms]) => ({
+                        role: code,
+                        model,
+                        perms: perms,
+                    })),
+                ],
+                permissions: permissions === undefined
+                    ? runtime.permissions
+                    : [
+                        ...runtime.permissions.filter((p) => p.role !== code),
+                        ...permissions.map((permission) => ({ role: code, permission })),
+                    ],
+            };
+            const before = grants(closureOf([code], runtime), runtime);
+            const after = grants(closureOf([code], proposed), proposed);
+            const holders = await holdersOf(env, code);
+            const others = await env.asSuperuser({ reason: 'role preview' }, (su) => find(su, 'auth.user_group', { user: { in: holders.map((h) => h.id) } }, [
+                'user',
+                'group',
+            ]));
+            const people = holders
+                .map((h) => {
+                const elsewhere = grants(closureOf(others
+                    .filter((o) => o['user'] === h.id && o['group'] !== code)
+                    .map((o) => String(o['group'])), runtime), runtime);
+                const diff = (from, to, kept) => [...to].filter((x) => !from.has(x) && !kept.has(x));
+                return {
+                    id: h.id,
+                    name: h.name,
+                    gains: [
+                        ...diff(before.levels, after.levels, elsewhere.levels).map(levelLabel),
+                        ...diff(before.permissions, after.permissions, elsewhere.permissions).map(permissionLabel),
+                    ],
+                    losses: [
+                        ...diff(after.levels, before.levels, elsewhere.levels).map(levelLabel),
+                        ...diff(after.permissions, before.permissions, elsewhere.permissions).map(permissionLabel),
+                    ],
+                };
+            })
+                .filter((p) => p.gains.length > 0 || p.losses.length > 0);
+            const models = [...new Set([...before.models.keys(), ...after.models.keys()])]
+                .map((name) => {
+                const was = before.models.get(name) ?? new Set();
+                const will = after.models.get(name) ?? new Set();
+                return {
+                    model: name,
+                    label: reg.models.get(name)?.model?.label ?? name,
+                    added: PERMS.filter((p) => will.has(p) && !was.has(p)),
+                    removed: PERMS.filter((p) => was.has(p) && !will.has(p)),
+                };
+            })
+                .filter((m) => m.added.length > 0 || m.removed.length > 0);
+            return { holders: holders.length, people, models };
+        }, { write: true });
+    });
+}

package/dist/portal/.kosh/bindings.js

@@ -1,4 +1,4 @@
-// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: bae647ca883975a1
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: f41721dc1c51ba8a
 // Bindings of module `portal`: import the definition API from here to get types scoped to what it can see.
 export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
 import { definitions } from '../../server/orm.js';