@magland/mochi 0.3.1

package/dist/api/admin.js

@@ -0,0 +1,416 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAdminApi = registerAdminApi;
+const fs = __importStar(require("fs"));
+const config_1 = require("../config");
+const layout_1 = require("../layout");
+const ops_1 = require("../ops");
+const redirects_1 = require("../redirects");
+const scan_1 = require("../scan");
+const siteshost_1 = require("../siteshost");
+const themes_1 = require("../themes");
+const perms_1 = require("../perms");
+const vault_1 = require("../vault");
+const auth_1 = require("./auth");
+// Administration: users, their tokens, collections, and the vault's own settings.
+//
+// Reading a user's tokens never returns a token. Only a SHA-256 hash is stored, so
+// there is nothing to return even if it were a good idea; what a caller gets is an
+// id, a creation time, and a scope, which is enough to revoke one.
+function registerAdminApi(app, root, limiter, lfs = null, engine, egress) {
+    // One context for the collection rename, as the other two surfaces build for
+    // theirs; see RepoContext in ops.ts.
+    const repoCtx = { lfs: lfs?.store, runs: engine };
+    /**
+     * A site admin, which is what a vault-wide setting takes. Not merely a
+     * collection owner: an owner should not restyle the whole vault or remove a
+     * collection that is not theirs, which is the same rule canSetTheme applies
+     * on the web.
+     */
+    const requireOwner = (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return null;
+        if (!(0, perms_1.isSiteAdmin)(auth)) {
+            (0, auth_1.apiError)(res, 403, 'site admin required (with an unrestricted token)');
+            return null;
+        }
+        return auth;
+    };
+    // ---- collections ----
+    /**
+     * Rename a collection, with everything in it. The same operation the web
+     * offers on a collection's settings page, and the same question: ownership
+     * of the collection. The owners file moves with the collection, so the
+     * owners after the rename are the owners before it.
+     *
+     * Unlike a repository rename this is not offered under a typed
+     * confirmation, here or on the web. A rename is undone by renaming back, and
+     * the confirmation belongs to deletion.
+     */
+    app.post('/api/collections/:name/rename', async (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const name = req.params.name;
+        if (!(0, scan_1.isValidName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable collection name');
+            return;
+        }
+        let isDir = false;
+        try {
+            isDir = fs.statSync((0, layout_1.collectionDir)(root, name)).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            (0, auth_1.apiError)(res, 404, `no collection ${name} in this vault`);
+            return;
+        }
+        const repos = (0, scan_1.listRepoDirs)(root, name).map(scan_1.displayName);
+        if (!(0, perms_1.canAdminCollection)(root, auth, name)) {
+            (0, auth_1.apiError)(res, 403, `you are not an owner of ${name}`);
+            return;
+        }
+        const to = (0, auth_1.stringField)((0, auth_1.bodyOf)(req), 'name')?.trim() ?? '';
+        if (!(0, scan_1.isValidName)(to)) {
+            (0, auth_1.apiError)(res, 400, 'a valid "name" is required (letters, digits, dot, underscore, dash; not a reserved word)');
+            return;
+        }
+        try {
+            await (0, ops_1.renameCollection)(root, name, to, repoCtx);
+            res.json({ name: to, renamedFrom: name, repos: repos.length, renamed: true });
+        }
+        catch (e) {
+            (0, auth_1.sendOpError)(res, e, 'could not rename the collection');
+        }
+    });
+    // Only an empty one, and only a directory: a collection is a directory, so
+    // removing it is an rmdir and refusing a non-empty one is the filesystem's own
+    // rule rather than a policy invented here.
+    app.delete('/api/collections/:name', (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const name = req.params.name;
+        if (!(0, perms_1.canAdminCollection)(root, auth, name)) {
+            (0, auth_1.apiError)(res, 403, `you are not an owner of ${name}`);
+            return;
+        }
+        if (!(0, scan_1.isValidName)(name)) {
+            (0, auth_1.apiError)(res, 400, 'that is not a usable collection name');
+            return;
+        }
+        const dir = (0, layout_1.collectionDir)(root, name);
+        let isDir = false;
+        try {
+            isDir = fs.statSync(dir).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            (0, auth_1.apiError)(res, 404, `no collection ${name} in this vault`);
+            return;
+        }
+        // Empty means the collection holds nothing but its own empty repos
+        // directory: no repository, nothing beside one, and nothing of the
+        // collection's own.
+        const repos = (0, layout_1.reposDir)(root, name);
+        const own = fs.readdirSync(dir).filter((n) => n !== layout_1.REPOS_DIR);
+        const inRepos = fs.existsSync(repos) ? fs.readdirSync(repos) : [];
+        if (own.length > 0 || inRepos.length > 0) {
+            (0, auth_1.apiError)(res, 409, `collection ${name} is not empty`);
+            return;
+        }
+        try {
+            fs.rmSync(dir, { recursive: true });
+        }
+        catch (e) {
+            (0, auth_1.apiError)(res, 409, `could not remove ${name}: ${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        // Any redirect that led here goes with it. A collection created later
+        // under this name would otherwise inherit the traffic a former name of
+        // this one still sends.
+        (0, redirects_1.forgetCollectionRedirects)(root, name);
+        res.json({ deleted: name });
+    });
+    // ---- users and their tokens ----
+    app.get('/api/users/:name', (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const state = (0, vault_1.loadVault)(root);
+        if (state.status !== 'ok') {
+            (0, auth_1.apiError)(res, 500, 'vault unavailable');
+            return;
+        }
+        const user = state.vault.users[req.params.name];
+        if (!user) {
+            (0, auth_1.apiError)(res, 404, `no user ${req.params.name}`);
+            return;
+        }
+        // A user may read their own record; reading anyone else's takes a site
+        // admin.
+        if (req.params.name !== auth.username && !(0, perms_1.isSiteAdmin)(auth)) {
+            (0, auth_1.apiError)(res, 403, 'site admin required to touch another user');
+            return;
+        }
+        res.json({
+            name: req.params.name,
+            siteAdmin: user.siteAdmin === true,
+            tokens: user.tokens.map((t) => ({ id: (0, vault_1.tokenId)(t), created: t.created ?? null, scope: t.scope ?? null })),
+        });
+    });
+    app.get('/api/users/:name/tokens', (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const state = (0, vault_1.loadVault)(root);
+        if (state.status !== 'ok') {
+            (0, auth_1.apiError)(res, 500, 'vault unavailable');
+            return;
+        }
+        const user = state.vault.users[req.params.name];
+        if (!user) {
+            (0, auth_1.apiError)(res, 404, `no user ${req.params.name}`);
+            return;
+        }
+        if (req.params.name !== auth.username && !(0, perms_1.isSiteAdmin)(auth)) {
+            (0, auth_1.apiError)(res, 403, 'site admin required to touch another user');
+            return;
+        }
+        // Never the token, and never the hash either: an id is what revocation
+        // takes, and the hash is a credential-shaped thing with no reason to travel.
+        res.json({
+            tokens: user.tokens.map((t) => ({ id: (0, vault_1.tokenId)(t), created: t.created ?? null, scope: t.scope ?? null })),
+        });
+    });
+    app.delete('/api/users/:name/tokens/:id', (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const state = (0, vault_1.loadVault)(root);
+        if (state.status !== 'ok') {
+            (0, auth_1.apiError)(res, 500, 'vault unavailable');
+            return;
+        }
+        const user = state.vault.users[req.params.name];
+        if (!user) {
+            (0, auth_1.apiError)(res, 404, `no user ${req.params.name}`);
+            return;
+        }
+        const ownToken = req.params.name === auth.username && (0, vault_1.tokenId)(auth.token) === req.params.id;
+        if (req.params.name !== auth.username && !(0, perms_1.isSiteAdmin)(auth)) {
+            (0, auth_1.apiError)(res, 403, 'site admin required to touch another user');
+            return;
+        }
+        let result;
+        try {
+            result = (0, vault_1.revokeToken)(root, req.params.name, req.params.id);
+        }
+        catch (e) {
+            (0, auth_1.apiError)(res, 500, e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (!result.revoked) {
+            (0, auth_1.apiError)(res, 404, `no token ${req.params.id} for ${req.params.name}`);
+            return;
+        }
+        // Revoking the token in use is allowed. It is reported rather than refused:
+        // locking yourself out is your business, and vault.json stays hand-editable.
+        res.json({ revoked: req.params.id, remaining: result.remaining, wasThisToken: ownToken });
+    });
+    app.delete('/api/users/:name', (req, res) => {
+        const auth = (0, auth_1.requireApiAuth)(root, limiter, req, res);
+        if (!auth)
+            return;
+        const state = (0, vault_1.loadVault)(root);
+        if (state.status !== 'ok') {
+            (0, auth_1.apiError)(res, 500, 'vault unavailable');
+            return;
+        }
+        const user = state.vault.users[req.params.name];
+        if (!user) {
+            (0, auth_1.apiError)(res, 404, `no user ${req.params.name}`);
+            return;
+        }
+        if (!(0, perms_1.isSiteAdmin)(auth)) {
+            (0, auth_1.apiError)(res, 403, 'site admin required to touch another user');
+            return;
+        }
+        // Deleting yourself would leave a vault an owner cannot administer except by
+        // hand, and unlike revoking one token it cannot be undone by minting another.
+        if (req.params.name === auth.username) {
+            (0, auth_1.apiError)(res, 409, 'a user cannot delete themselves; another admin can, or edit vault.json by hand');
+            return;
+        }
+        if (String(req.query.confirm ?? '') !== req.params.name) {
+            (0, auth_1.apiError)(res, 400, `to remove this user and every token they hold, send ?confirm=${req.params.name}`);
+            return;
+        }
+        const removed = (0, vault_1.removeUser)(root, req.params.name);
+        // Their grants go with them: a collaborator entry or an owners listing
+        // left behind would belong to whoever is given this name next.
+        if (removed)
+            (0, perms_1.removeUserGrants)(root, req.params.name);
+        res.json({ deleted: req.params.name, removed });
+    });
+    // ---- vault settings ----
+    app.get('/api/config', (req, res) => {
+        const auth = requireOwner(req, res);
+        if (!auth)
+            return;
+        const config = (0, config_1.loadConfig)(root);
+        res.json({ ...config, themes: (0, themes_1.themeNames)() });
+    });
+    app.patch('/api/config', (req, res) => {
+        const auth = requireOwner(req, res);
+        if (!auth)
+            return;
+        const body = (0, auth_1.bodyOf)(req);
+        const changes = {};
+        if (body.theme !== undefined) {
+            if (typeof body.theme !== 'string' || !(0, themes_1.findTheme)(body.theme)) {
+                (0, auth_1.apiError)(res, 400, `"theme" must be one of: ${(0, themes_1.themeNames)().join(', ')} (default ${themes_1.DEFAULT_THEME})`);
+                return;
+            }
+            changes.theme = body.theme;
+        }
+        if (body.ci !== undefined) {
+            if (typeof body.ci !== 'object' || body.ci === null || Array.isArray(body.ci)) {
+                (0, auth_1.apiError)(res, 400, '"ci" must be an object');
+                return;
+            }
+            const ci = body.ci;
+            const current = (0, config_1.loadConfig)(root).ci;
+            const number = (v, fallback, min) => typeof v === 'number' && Number.isFinite(v) && v >= min ? Math.floor(v) : fallback;
+            changes.ci = {
+                runs: number(ci.runs, current.runs, 0),
+                days: number(ci.days, current.days, 0),
+                artifactMb: number(ci.artifactMb, current.artifactMb, 1),
+            };
+        }
+        // The hostname whose subdomains serve repository sites. Every reader of it
+        // calls loadConfig per request, so a change here is in effect on the next
+        // one; it is the setting a hosted vault most needs to change, and reaching a
+        // volume to edit config.json by hand is the worst step in that whole path.
+        if (body.sites !== undefined) {
+            if (typeof body.sites !== 'object' || body.sites === null || Array.isArray(body.sites)) {
+                (0, auth_1.apiError)(res, 400, '"sites" must be an object');
+                return;
+            }
+            const sites = body.sites;
+            if (typeof sites.host !== 'string') {
+                (0, auth_1.apiError)(res, 400, '"sites" takes a "host" string; send "" to serve sites on the forge host again');
+                return;
+            }
+            const host = (0, siteshost_1.normalizeHostname)(sites.host);
+            // loadConfig ignores a value that is not a hostname and uses the default,
+            // which is right for a hand-edited file and wrong here: a caller who just
+            // asked for a change should be told it was not one, rather than reading
+            // back a value they did not send.
+            if (host !== '' && !(0, config_1.isPlausibleHostname)(host)) {
+                (0, auth_1.apiError)(res, 400, `"${sites.host}" is not a hostname: give at least two labels of letters, digits, and interior hyphens, ` +
+                    'with no scheme, port, or path');
+                return;
+            }
+            changes.sites = { host };
+        }
+        // One field of the limits block is writable, and only the one: the daily
+        // egress cap is read per request, so a change to it is in force on the next
+        // one. The rest of the block is read at startup, so a route that changed it
+        // would report a change the running server had not made.
+        //
+        // The whole block is written back, merged over what is on disk, because
+        // saveConfig replaces a top-level key rather than merging into it.
+        if (body.limits !== undefined) {
+            if (typeof body.limits !== 'object' || body.limits === null || Array.isArray(body.limits)) {
+                (0, auth_1.apiError)(res, 400, '"limits" must be an object');
+                return;
+            }
+            const limits = body.limits;
+            const unknown = Object.keys(limits).filter((k) => k !== 'egressGbPerDay');
+            if (unknown.length > 0) {
+                (0, auth_1.apiError)(res, 400, `only "egressGbPerDay" can be set here; ${unknown.join(', ')} ${unknown.length === 1 ? 'is' : 'are'} read when the server starts, so edit config.json in the vault and restart`);
+                return;
+            }
+            const gb = limits.egressGbPerDay;
+            if (typeof gb !== 'number' || !Number.isFinite(gb) || gb < 0) {
+                (0, auth_1.apiError)(res, 400, '"egressGbPerDay" must be a number of gigabytes, 0 to send without a daily limit');
+                return;
+            }
+            changes.limits = { ...(0, config_1.loadConfig)(root).limits, egressGbPerDay: gb };
+        }
+        if (Object.keys(changes).length === 0) {
+            (0, auth_1.apiError)(res, 400, 'nothing to change; provide "theme", "ci", "sites", and/or "limits"');
+            return;
+        }
+        // network is deliberately not writable here, and neither is the rest of
+        // limits: both are read once at startup, so a route that changed them would
+        // report a change the running server had not made. docs/deploying.md says to
+        // edit config.json and restart.
+        res.json((0, config_1.saveConfig)(root, changes));
+    });
+    // ---- outgoing bytes ----
+    /**
+     * What the vault has sent today, per repository, and what it sent on the days
+     * before. The same numbers /admin/egress shows, for anyone who would rather
+     * watch a bill from a script.
+     *
+     * Owner scope, like the rest of the vault's own settings: the breakdown says
+     * which repositories are being read and how heavily, which is more than a
+     * collection administrator is owed about a collection that is not theirs.
+     */
+    app.get('/api/egress', (req, res) => {
+        const auth = requireOwner(req, res);
+        if (!auth)
+            return;
+        if (!egress) {
+            (0, auth_1.apiError)(res, 503, 'this server is not counting outgoing bytes');
+            return;
+        }
+        const snap = egress.snapshot();
+        res.json({
+            ...snap,
+            // Said here as well as on the page: a caller adding these numbers up
+            // against a hosting bill needs to know what is missing from them.
+            lfsBucketExcluded: lfs?.offloaded ?? false,
+        });
+    });
+}

package/dist/api/auth.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiError = apiError;
+exports.requireApiAuth = requireApiAuth;
+exports.requireRepo = requireRepo;
+exports.requirePush = requirePush;
+exports.requireRepoAdmin = requireRepoAdmin;
+exports.sendOpError = sendOpError;
+exports.bodyOf = bodyOf;
+exports.stringField = stringField;
+exports.stringsField = stringsField;
+exports.limitParam = limitParam;
+const ops_1 = require("../ops");
+const perms_1 = require("../perms");
+const scan_1 = require("../scan");
+const vault_1 = require("../vault");
+// Authorization for the JSON API, in one place because there is more than one
+// file of routes behind it. Only bearer tokens are accepted: session cookies
+// never authorize an API call, and git's Basic auth never does either.
+//
+// Anonymous reads are deliberately not offered. The web is where anonymous
+// reading lives, and requiring a token on /api keeps one rule for the whole
+// surface.
+//
+// Two transports over one domain layer is two places to forget a role check, so
+// the shape here is not a helper a handler may neglect to call. requireRepo and
+// requirePush are what produce the repository a domain function needs, and they
+// load the repository and the scope together: a handler that skips the check has
+// nothing to pass to the domain function.
+function apiError(res, status, message) {
+    res.status(status).json({ error: message });
+}
+/**
+ * The caller's identity, or null having already answered with the refusal. A
+ * handler that ignores the null is a handler that runs unauthenticated, so the
+ * shape to write is `const auth = requireApiAuth(...); if (!auth) return;`.
+ */
+function requireApiAuth(root, limiter, req, res) {
+    const state = (0, vault_1.loadVault)(root);
+    if (state.status === 'missing') {
+        apiError(res, 401, 'no vault.json in this vault; restart the server to initialize one');
+        return null;
+    }
+    if (state.status === 'error') {
+        apiError(res, 500, `vault.json could not be read: ${state.message}`);
+        return null;
+    }
+    const m = (req.get('authorization') ?? '').match(/^bearer\s+(.+)$/i);
+    // A missing Authorization header is not a failed attempt and is not charged: a
+    // browser wandering onto an API path with no header would otherwise consume a
+    // real client's budget.
+    if (!m) {
+        apiError(res, 401, 'missing bearer token: send Authorization: Bearer <token>');
+        return null;
+    }
+    // Bearer tokens carry no username, so only the coarse per-address window
+    // really applies to them. Checking a credential is a loadVault and a hash, so
+    // the cheapest request an attacker can send is one of the more expensive ones
+    // this server can answer.
+    const allowed = limiter.allow(req, null);
+    if (!allowed.ok) {
+        res.setHeader('Retry-After', String(allowed.retryAfter));
+        apiError(res, 429, 'too many failed authentication attempts; try again later');
+        return null;
+    }
+    const auth = (0, vault_1.authenticateToken)(state.vault, m[1].trim());
+    if (!auth) {
+        limiter.fail(req, null);
+        apiError(res, 401, 'invalid token');
+        return null;
+    }
+    return auth;
+}
+// The address a commit made over the API is attributed to. The host is the
+// vault's own, as it is for a commit made in the browser, so that the two
+// interfaces do not attribute the same person differently.
+function actorFor(req, auth) {
+    const host = (req.get('host') ?? 'localhost').replace(/:\d+$/, '');
+    return { username: auth.username, email: `${auth.username}@noreply.${host}` };
+}
+/**
+ * The repository named by :collection and :repo, for a caller allowed to read
+ * it. `:repo` is accepted with or without the .git suffix, as findRepo already
+ * allows everywhere else. A private repository the caller has no role on gets
+ * the same 404 an absent one gets, so a private name proves nothing by
+ * existing.
+ */
+function requireRepo(root, limiter, req, res) {
+    const auth = requireApiAuth(root, limiter, req, res);
+    if (!auth)
+        return null;
+    const collection = req.params.collection;
+    const repo = (0, scan_1.findRepo)(root, collection, req.params.repo);
+    if (!repo || !(0, perms_1.canReadRepo)(root, auth, repo)) {
+        apiError(res, 404, `no repository ${collection}/${req.params.repo} in this vault`);
+        return null;
+    }
+    return { auth, repo };
+}
+/** The same, for a caller who may also push to it. */
+function requirePush(root, limiter, req, res) {
+    const found = requireRepo(root, limiter, req, res);
+    if (!found)
+        return null;
+    if (!(0, perms_1.canWriteRepo)(root, found.auth, found.repo)) {
+        apiError(res, 403, `you do not have the write role on ${found.repo.collection}/${found.repo.name}`);
+        return null;
+    }
+    return { ...found, actor: actorFor(req, found.auth) };
+}
+/** The same, for an operation that needs the admin role on the repository. */
+function requireRepoAdmin(root, limiter, req, res) {
+    const found = requireRepo(root, limiter, req, res);
+    if (!found)
+        return null;
+    if (!(0, perms_1.canAdminRepo)(root, found.auth, found.repo)) {
+        apiError(res, 403, `you do not have the admin role on ${found.repo.collection}/${found.repo.name}`);
+        return null;
+    }
+    return { ...found, actor: actorFor(req, found.auth) };
+}
+/**
+ * Turn a domain failure into a response, once, rather than per route.
+ *
+ * OpError already carries the distinction the caller needs, and mapping it here
+ * is what keeps a validation failure from being reported as a 500. `nochange` is
+ * a success: the caller asked for a state the vault is already in.
+ */
+function sendOpError(res, e, fallback = 'the operation failed') {
+    if (!(e instanceof ops_1.OpError)) {
+        console.error(e);
+        apiError(res, 500, fallback);
+        return;
+    }
+    if (e.kind === 'nochange') {
+        res.json({ changed: false, message: e.message });
+        return;
+    }
+    apiError(res, (0, ops_1.opErrorStatus)(e.kind), e.message);
+}
+/** A route body, with the shape checked far enough to read fields off it. */
+function bodyOf(req) {
+    const body = req.body;
+    return typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
+}
+/** A required string field. */
+function stringField(body, name) {
+    const v = body[name];
+    return typeof v === 'string' ? v : null;
+}
+/** An optional list-of-strings field: undefined when absent, null when malformed. */
+function stringsField(body, name) {
+    const v = body[name];
+    if (v === undefined || v === null)
+        return undefined;
+    if (Array.isArray(v) && v.every((x) => typeof x === 'string'))
+        return v;
+    return null;
+}
+/** A positive integer from a query parameter, within a cap. */
+function limitParam(raw, fallback, max) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        return fallback;
+    return Math.min(n, max);
+}