@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/utils/renameLinkRewrite.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Rewrite `[Old Title]` link targets to a page's new title (#1094).
+ *
+ * When a page is renamed, every `[Old Title]` in every other page stops
+ * resolving. #1082 answered that with an in-memory former-title map consulted
+ * after live resolution fails. That map has no durable backing — a restart
+ * forgets every rename — so it works right up until it silently stops.
+ *
+ * Rewriting the content instead makes the referring pages *correct*, rather
+ * than correct-looking because a lookup happens to still be warm.
+ *
+ * ## What this module is, and is not
+ *
+ * This is the text half only: pure, synchronous, no engine, no I/O. Given
+ * content and a rename it returns new content and a report. Deciding which
+ * pages to feed it, bounding the pass, writing the results and surviving a
+ * lost race are the caller's job — see `WikiRoutes.rewriteInboundLinksAfterRename`.
+ *
+ * The split is deliberate: the matching rules below are where the subtle bugs
+ * live, and they are worth testing without a server.
+ *
+ * ## Matching rules
+ *
+ * The link syntax is the parser's own (`WIKI_LINK_PATTERN_SOURCE`), imported
+ * rather than copied so the two cannot drift. It admits three forms:
+ *
+ * | Form                       | Target       | Also the display text? |
+ * |----------------------------|--------------|------------------------|
+ * | `[Title]`                  | `Title`      | yes                    |
+ * | `[Display\|Title]`          | `Title`      | no                     |
+ * | `[Display\|Title\|attrs]`    | `Title`      | no                     |
+ *
+ * A target may carry a fragment — `Title#slug` or `Title#section=Heading Name`
+ * — which is preserved verbatim; only the part before the first `#` is
+ * compared and replaced.
+ *
+ * __Case sensitivity differs by form, on purpose.__ In `[Display|Title]` the
+ * target is invisible to the reader, so a case variant is rewritten: nothing a
+ * human wrote changes. In `[Title]` the target *is* the display text, so only
+ * a byte-exact match is rewritten — silently recasing an author's prose to
+ * match a title is an edit they did not ask for.
+ *
+ * __Non-page targets are left alone__ by the same tests the parser uses to
+ * classify them: external URLs, `mailto:`, bare `#fragment`, absolute paths,
+ * and `Site:path` InterWiki references.
+ *
+ * __Markdown links are not touched.__ `[text](Target)` is excluded by the
+ * pattern's trailing `(?!\()`. The link graph does record them as edges, so a
+ * page linking that way can appear in the referrer set and come back with zero
+ * rewrites; that shows up in `unchangedTargets` rather than being silently
+ * counted as done.
+ *
+ * ## What it deliberately does not catch
+ *
+ * A link whose text only *fuzzy*-matches the old title — `[Old Titles]`
+ * resolving to `Old Title` through `PageNameMatcher` — is not rewritten. The
+ * link graph stores the *resolved* name, so such a page is in the referrer set
+ * and will come back unchanged. That is reported, not repaired: turning
+ * `[Old Titles]` into `[New Title]` rewrites the author's wording, and those
+ * links keep resolving through the #1082 map for as long as it exists.
+ */
+/** Outcome of rewriting one page's content. */
+export interface LinkRewriteResult {
+    /** The content, rewritten. Identical to the input when `rewritten` is 0. */
+    content: string;
+    /** How many link targets were replaced. */
+    rewritten: number;
+    /**
+     * Internal page targets seen and left as they were, de-duplicated and in
+     * first-seen order. The caller logs these for a referrer that yielded no
+     * rewrites: it is the visible trace of a fuzzy variant, a markdown-syntax
+     * link, or a link-graph edge that no longer reflects the content.
+     */
+    unchangedTargets: string[];
+}
+/**
+ * What a caller decides about one link target it was shown.
+ *
+ * @param base - The target as written, without any `#fragment`.
+ * @param targetIsDisplayText - True for `[Title]`, where the target IS the
+ *   text the reader sees, and false for the piped forms, where it is not.
+ *   The rewriting rule differs by form — see the module comment.
+ * @returns The target to write instead, or `null` to leave the link alone.
+ *   The fragment is re-attached by the caller; a resolver never sees one.
+ */
+export type LinkTargetResolver = (base: string, targetIsDisplayText: boolean) => string | null;
+/**
+ * Rewrite link targets by the caller's rule — the matcher, once.
+ *
+ * The rename rewrite below and the private-link migration (#1457) decide
+ * different things about a target and agree on everything else: which
+ * bracket forms are links at all, that a task-list checkbox is not one, that
+ * external, mail, anchor, absolute and InterWiki targets are left alone, and
+ * that a `#fragment` survives. A second pass with its own regex would be a
+ * second place for those to drift, so both come through here.
+ *
+ * @param content - The page's markdown.
+ * @param resolve - What to do with each internal target seen.
+ * @returns The rewritten content and a report.
+ */
+export declare function rewriteLinkTargetsBy(content: string, resolve: LinkTargetResolver): LinkRewriteResult;
+/**
+ * Rewrite links pointing at `oldTitle` so they point at `newTitle`.
+ *
+ * @param content - The referring page's markdown.
+ * @param oldTitle - The title the page was renamed away from.
+ * @param newTitle - The title it now has.
+ * @returns The rewritten content and a report. Returns the input unchanged
+ *   (and `rewritten: 0`) when there is nothing to do, including when either
+ *   title is blank or the two are equal.
+ */
+export declare function rewriteLinkTargets(content: string, oldTitle: string, newTitle: string): LinkRewriteResult;

package/lib/src/utils/roleGrants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What each role is granted, read from the access policies (#1521).
+ *
+ * For the admin user forms: beside each role, the permissions its policies
+ * grant, so an admin can see that `contributor` already carries everything
+ * `reader` does under the shipped policies. Read from the merged policies —
+ * core, add-ons and the instance's own — so it shows what this site grants.
+ *
+ * Display only. Roles are independent in the code; whether a request is
+ * allowed is still decided by the evaluator, policy by policy and resource by
+ * resource. A grant that applies only to some resources (a policy naming
+ * particular pages or system-categories) is marked `limited`.
+ */
+import type { Policy } from '../types/Policy.js';
+export interface RoleGrant {
+    action: string;
+    /** True when every policy granting it applies to some resources only. */
+    limited: boolean;
+    /** For a limited grant, the resource types it is limited to — `vault` reads "in your own vaults" (#1539). */
+    where: string[];
+}
+export interface RoleGrants {
+    allows: RoleGrant[];
+    /** Actions a deny policy names for this role. */
+    denies: string[];
+}
+/**
+ * Every role a policy names, with what its policies allow and deny — the one
+ * reading of "what a role grants" (#1539): the user forms, the profile, the
+ * admin roles page and `PolicyDecisionPoint.rolePermissions` all come from
+ * here. Policies are applied lowest priority first, so a deny takes away what
+ * a lower-priority allow gave and an allow above it gives it back — the order
+ * the evaluator's first-match-by-priority decides in.
+ */
+export declare function roleGrants(policies: readonly Policy[]): Record<string, RoleGrants>;

package/lib/src/utils/safeRedirect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * safeRedirect — constrain a request-supplied redirect target to this site (#1041).
+ *
+ * `POST /login` passed `req.body.redirect` straight to `res.redirect`, so the
+ * login endpoint sent the browser anywhere the request named:
+ *
+ *   redirect=//example.com/   →   HTTP/1.1 302   Location: //example.com/
+ *
+ * That is the worst place in the application to have an open redirect. The
+ * victim authenticates against the real site, sees a genuine successful login,
+ * and is then handed to an attacker-controlled page — a clone asking them to
+ * "sign in again" is very convincing at that point.
+ *
+ * The rule is deliberately a strict allow-list rather than a blocklist of bad
+ * prefixes: a single leading slash, and nothing that could be read as a host or
+ * a scheme. Blocklists here fail to the open case, which is the wrong direction
+ * for a redirect sink.
+ */
+/**
+ * Return `target` when it is a same-site path, otherwise `/`.
+ *
+ * Accepts: `/`, `/view/Welcome`, `/search?q=x#frag`
+ *
+ * Rejects, among others:
+ *   - `//evil.example`      — protocol-relative; the browser reads it as a host
+ *   - `https://evil.example`, `javascript:…`, `data:…` — any scheme
+ *   - `/\evil.example`      — browsers normalise the backslash to `/`
+ *   - `\\evil.example`, or anything not starting with `/`
+ *   - a CR/LF, which would let a caller inject a second header
+ */
+export declare function safeRedirect(target: unknown): string;
+export default safeRedirect;

package/lib/src/utils/schedule.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The schedule engine for scheduled jobs (#1713, epic #1611).
+ *
+ * A schedule is an iCalendar recurrence rule (RFC 5545 RRULE), the format the
+ * calendar add-on already stores, with a start (`dtstart`) and a time zone.
+ * Cron is not used: it cannot say "every 30 days" or "the last business day".
+ * Named shorthands (`daily 06:00`, `end-of-month`, …) expand to an RRULE.
+ *
+ * Recurrence is computed on wall-clock time and then placed in the time zone,
+ * so daylight saving does what a person expects:
+ *   - spring forward: a slot inside the skipped hour runs at the next valid
+ *     instant (02:30 becomes 03:30), rather than not at all;
+ *   - fall back: a slot inside the repeated hour runs once, at its first
+ *     occurrence.
+ * A date that does not exist is skipped, as RFC 5545 says: `BYMONTHDAY=31`
+ * skips short months; the last day of a month is `BYMONTHDAY=-1`. RFC 7529
+ * (RSCALE / SKIP) is not used (operator, 2026-10-08).
+ *
+ * Pure: no configuration is read here. The caller passes the default time zone
+ * (`ngdpbase.default.timezone`) and the minimum interval.
+ *
+ * @module utils/schedule
+ */
+/** What a job declares. A string is a shorthand or a bare RRULE (`FREQ=…`). */
+export type ScheduleInput = string | {
+    rrule: string;
+    dtstart?: string;
+    tz?: string;
+};
+export interface ScheduleOptions {
+    /** IANA time zone used when the schedule names none. */
+    defaultTimeZone: string;
+    /** Slots closer together than this are refused. Default 60 000 ms. */
+    minIntervalMs?: number;
+}
+export interface Schedule {
+    /** The RRULE that was compiled (after shorthand expansion). */
+    rrule: string;
+    /** The wall-clock start the recurrence is counted from, e.g. `2000-01-01T00:00:00`. */
+    dtstart: string;
+    timeZone: string;
+    /** The first slot strictly after `after`, or null when the rule has ended. */
+    nextSlot(after: Date): Date | null;
+    /** Every slot in `[from, to]`, oldest first. */
+    slotsBetween(from: Date, to: Date): Date[];
+}
+/** A shorthand's RRULE, a bare RRULE as given, or an error naming what was not understood. */
+export declare function expandShorthand(text: string): string;
+/**
+ * Compile a schedule. Throws, with a message a job author can act on, for an
+ * unknown shorthand, an invalid rule, an unknown time zone, `FREQ=SECONDLY`,
+ * an `RSCALE` other than GREGORIAN, or slots closer than the minimum interval.
+ */
+export declare function parseSchedule(input: ScheduleInput, options: ScheduleOptions): Schedule;

package/lib/src/utils/secretFileMode.d.ts

@@ -0,0 +1,17 @@
+export declare const SECRET_FILE_MODE = 384;
+export declare const SECRET_DIR_MODE = 448;
+/**
+ * Check an existing secret file at boot. Missing is fine (it is created
+ * owner-only on first write). Returns a line to log when it was tightened.
+ * Throws, naming both UIDs, when another account owns it.
+ */
+export declare function secureExistingSecretFile(file: string): string | null;
+/**
+ * Make a directory holding secrets owner-only, creating it when absent.
+ * Best effort on a filesystem that does not honour modes (an SMB share):
+ * returns a warning instead of failing, since refusing to write a backup
+ * over it would be worse than writing it with the share's permissions.
+ */
+export declare function ensureSecretDir(dir: string): string | null;
+/** After writing a secret file directly (not through writeFileAtomic's mode), make it owner-only. */
+export declare function chmodSecretFile(file: string): string | null;

package/lib/src/utils/seededShippedPages.d.ts

@@ -0,0 +1,45 @@
+export declare const SEEDED_SHIPPED_PAGES_FILE = "seeded-shipped-pages.json";
+/** Why a site declined a shipped page, and who decided. */
+export interface DeclinedShippedPage {
+    /** When it was declined (ISO 8601) */
+    at: string;
+    /** Who declined it */
+    by: string;
+    /** The conflict that prompted it */
+    reason: string;
+}
+export declare class SeededShippedPages {
+    private readonly filePath;
+    private readonly data;
+    private constructor();
+    /**
+     * Load the record from the instance data folder. A missing file is an empty
+     * record; an unreadable one is an error, so the seeder cannot mistake a broken
+     * record for a site that has seeded nothing.
+     */
+    static load(instanceDataFolder: string): Promise<SeededShippedPages>;
+    /** Whether this site has a record for the source at all. */
+    hasSource(sourceId: string): boolean;
+    /** Whether the uuid was ever seeded from the source on this site. */
+    has(sourceId: string, uuid: string): boolean;
+    /** Whether the uuid was ever seeded from any source on this site. */
+    hasUuid(uuid: string): boolean;
+    /** Record a uuid as seeded from the source. Returns true when it was not recorded before. */
+    add(sourceId: string, uuid: string, at?: string): boolean;
+    /** Whether this site declined the uuid from that source (#1412). */
+    isDeclined(sourceId: string, uuid: string): boolean;
+    /** Why this site declined the uuid, or undefined. */
+    declinedEntry(sourceId: string, uuid: string): DeclinedShippedPage | undefined;
+    /** Every declined uuid of a source, as uuid → entry. */
+    declinedOf(sourceId: string): Record<string, DeclinedShippedPage>;
+    /** Every source that has declines, as source id → uuid → entry. */
+    allDeclined(): Record<string, Record<string, DeclinedShippedPage>>;
+    /** Decline a uuid from a source. Returns true when it was not declined before. */
+    decline(sourceId: string, uuid: string, entry: DeclinedShippedPage): boolean;
+    /** Undo a decline. Returns true when there was one. */
+    allow(sourceId: string, uuid: string): boolean;
+    /** Start an empty record for the source, so `hasSource` is true from now on. */
+    startSource(sourceId: string): void;
+    save(): Promise<void>;
+    private source;
+}

package/lib/src/utils/sensitiveValues.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Which configuration values may be shown, and to whom (#1750).
+ *
+ * One declaration, `ngdpbase.config.sensitive-values` (renamed from
+ * `ngdpbase.config.secret-keys`, still read as an alias), maps a key to a level:
+ *
+ *   - `secret`    — never shown except to a holder of `secret-reveal` (which
+ *                   asks for a fresh sign-in), never written to the audit log
+ *                   or a log line;
+ *   - `sensitive` — shown only to a holder of `admin-read`: how the instance is
+ *                   run (the access policies, storage paths, outside services).
+ *
+ * A key that isn't listed but whose name looks like a secret is treated as
+ * `secret` — a backstop, so a forgotten entry fails closed. The same backstop
+ * hides secret-looking fields nested inside an object value (an OIDC client's
+ * `client_secret` inside `oidc-auth-server.clients`).
+ *
+ * Hidden values are replaced on the server, before any HTML is built: they
+ * never reach a page, its source or the parse cache.
+ *
+ * @module utils/sensitiveValues
+ */
+export declare const SENSITIVE_VALUES_KEY = "ngdpbase.config.sensitive-values";
+/** The list's name before #1750; still read, with a boot warning to rename it. */
+export declare const LEGACY_SECRET_KEYS_KEY = "ngdpbase.config.secret-keys";
+export type ValueLevel = 'secret' | 'sensitive';
+/** What a viewer may see: sensitive values (`admin-read`), secret values (`secret-reveal`). */
+export interface ValueViewer {
+    sensitive: boolean;
+    secret: boolean;
+}
+/** Whether a key or field name looks like a secret (the backstop's test; also `npm run lint:sensitive`). */
+export declare function looksSecret(name: string): boolean;
+/** What a hidden value is shown as. */
+export declare const HIDDEN = "(hidden)";
+type Read = (key: string, fallback: unknown) => unknown;
+/**
+ * The declared levels: the legacy list's keys as `secret`, then the new map
+ * (`"secret"`, `"sensitive"`, `true` = secret; `false` / `null` removes an
+ * entry, so an instance can override a shipped one).
+ */
+export declare function valueLevels(read: Read): Map<string, ValueLevel>;
+/** The keys declared `secret`: what logs, the audit log and the admin screen never print. */
+export declare function secretKeys(read: Read): string[];
+/**
+ * A value's level: as declared, else `secret` when the key's name looks like
+ * one and the value is a string. A boolean or number can't be a secret, so
+ * `ngdpbase.auth.password.enabled` stays visible; only a declared entry hides
+ * whatever its type.
+ */
+export declare function levelOf(key: string, levels: Map<string, ValueLevel>, value?: unknown): ValueLevel | null;
+/** Whether the legacy list is still set (to warn at boot). */
+export declare function usesLegacyName(read: Read): boolean;
+/**
+ * The value a viewer may see for a key: itself, or `HIDDEN`. An empty value
+ * is shown as it is — "not set" reveals nothing.
+ */
+export declare function shownValue(key: string, value: unknown, levels: Map<string, ValueLevel>, viewer: ValueViewer): unknown;
+export {};

package/lib/src/utils/sensitiveValues.js

@@ -0,0 +1,106 @@
+/**
+ * Which configuration values may be shown, and to whom (#1750).
+ *
+ * One declaration, `ngdpbase.config.sensitive-values` (renamed from
+ * `ngdpbase.config.secret-keys`, still read as an alias), maps a key to a level:
+ *
+ *   - `secret`    — never shown except to a holder of `secret-reveal` (which
+ *                   asks for a fresh sign-in), never written to the audit log
+ *                   or a log line;
+ *   - `sensitive` — shown only to a holder of `admin-read`: how the instance is
+ *                   run (the access policies, storage paths, outside services).
+ *
+ * A key that isn't listed but whose name looks like a secret is treated as
+ * `secret` — a backstop, so a forgotten entry fails closed. The same backstop
+ * hides secret-looking fields nested inside an object value (an OIDC client's
+ * `client_secret` inside `oidc-auth-server.clients`).
+ *
+ * Hidden values are replaced on the server, before any HTML is built: they
+ * never reach a page, its source or the parse cache.
+ *
+ * @module utils/sensitiveValues
+ */
+import { enabledEntries } from './configFiles.js';
+export const SENSITIVE_VALUES_KEY = 'ngdpbase.config.sensitive-values';
+/** The list's name before #1750; still read, with a boot warning to rename it. */
+export const LEGACY_SECRET_KEYS_KEY = 'ngdpbase.config.secret-keys';
+/** Names that look like a secret, for keys and for fields inside object values. */
+const SECRET_NAME_PATTERN = /secret|passw(or)?d|token|credential|api[-_]?key|private[-_]?key/i;
+/** Whether a key or field name looks like a secret (the backstop's test; also `npm run lint:sensitive`). */
+export function looksSecret(name) {
+    return SECRET_NAME_PATTERN.test(name);
+}
+/** What a hidden value is shown as. */
+export const HIDDEN = '(hidden)';
+/**
+ * The declared levels: the legacy list's keys as `secret`, then the new map
+ * (`"secret"`, `"sensitive"`, `true` = secret; `false` / `null` removes an
+ * entry, so an instance can override a shipped one).
+ */
+export function valueLevels(read) {
+    const levels = new Map();
+    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})))
+        levels.set(key, 'secret');
+    const declared = read(SENSITIVE_VALUES_KEY, {});
+    if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
+        for (const [key, level] of Object.entries(declared)) {
+            if (level === 'secret' || level === true)
+                levels.set(key, 'secret');
+            else if (level === 'sensitive')
+                levels.set(key, 'sensitive');
+            else
+                levels.delete(key);
+        }
+    }
+    else {
+        for (const key of enabledEntries(declared))
+            levels.set(key, 'secret');
+    }
+    return levels;
+}
+/** The keys declared `secret`: what logs, the audit log and the admin screen never print. */
+export function secretKeys(read) {
+    return [...valueLevels(read)].filter(([, level]) => level === 'secret').map(([key]) => key);
+}
+/**
+ * A value's level: as declared, else `secret` when the key's name looks like
+ * one and the value is a string. A boolean or number can't be a secret, so
+ * `ngdpbase.auth.password.enabled` stays visible; only a declared entry hides
+ * whatever its type.
+ */
+export function levelOf(key, levels, value) {
+    const declared = levels.get(key);
+    if (declared)
+        return declared;
+    return looksSecret(key) && typeof value === 'string' ? 'secret' : null;
+}
+/** Whether the legacy list is still set (to warn at boot). */
+export function usesLegacyName(read) {
+    return enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})).length > 0;
+}
+/** Secret-looking fields inside an object value, hidden; the rest kept. */
+function hideNestedSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(hideNestedSecrets);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = looksSecret(k) && typeof v === 'string' && v !== '' ? HIDDEN : hideNestedSecrets(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The value a viewer may see for a key: itself, or `HIDDEN`. An empty value
+ * is shown as it is — "not set" reveals nothing.
+ */
+export function shownValue(key, value, levels, viewer) {
+    const empty = value === undefined || value === null || value === '';
+    const level = levelOf(key, levels, value);
+    if (level === 'secret' && !viewer.secret)
+        return empty ? value : HIDDEN;
+    if (level === 'sensitive' && !viewer.sensitive)
+        return empty ? value : HIDDEN;
+    return viewer.secret ? value : hideNestedSecrets(value);
+}

package/lib/src/utils/sessionEnd.d.ts

@@ -0,0 +1,12 @@
+export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded';
+export declare function endSession(engine: {
+    getManager(name: string): unknown;
+}, session: {
+    username?: unknown;
+    privateStoreHandle?: unknown;
+    pendingConnection?: unknown;
+    actingFor?: unknown;
+} | null | undefined, reason: SessionEndReason, from: {
+    ipAddress?: string;
+    userAgent?: string;
+}): void;

package/lib/src/utils/sessionGeneration.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Password-change session generation (#1482).
+ *
+ * A user record carries `sessionGeneration`, a counter raised whenever the
+ * account's password changes — by the owner, an administrator, the recovery
+ * words (#1452) or the offline reset script. A session is stamped with the
+ * counter when it signs in; a request whose session carries an older value is
+ * signed out. That ends every other session of the account without finding
+ * sessions on disk, at the cost of one comparison per request.
+ *
+ * An account that has never changed its password is at 0, and a session
+ * signed in before this existed carries nothing, which reads as 0: existing
+ * sessions stay signed in until the first password change.
+ */
+interface HasGeneration {
+    sessionGeneration?: number;
+}
+/** The account's current generation; 0 when it has never been raised. */
+export declare function sessionGenerationOf(user: HasGeneration | null | undefined): number;
+/** Raise the account's generation, in place, and return the new value. */
+export declare function bumpSessionGeneration(user: HasGeneration): number;
+/** Whether a session stamped with `stamped` still belongs to the account as it is now. */
+export declare function sessionIsCurrent(stamped: unknown, user: HasGeneration | null | undefined): boolean;
+export {};

package/lib/src/utils/sessionIdle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session idle timeout (#1546).
+ *
+ * `ngdpbase.session.idle-timeout-minutes` ends a signed-in session after that
+ * many minutes with no request. Shipped at 10080 (7 days, #1767); `0` is off.
+ * It is separate from `ngdpbase.session.max-age`, the absolute cap from
+ * sign-in (`sessionLimits.ts`); a value at or above that cap has no effect.
+ *
+ * Enforced server-side on the next request — never only by a browser timer,
+ * which a closed laptop or a copied cookie would not run.
+ *
+ * Writing the last-activity time on every request would save the session on
+ * every request, which the file store pays for, so it is written at most once
+ * per `touchEveryMs`: a session may then end up to that much later than the
+ * exact limit, never earlier.
+ */
+/** The configured limit in milliseconds; 0 when off or not a positive number. */
+export declare function idleTimeoutMs(minutes: unknown): number;
+/** How stale the recorded activity may get before it is written again. */
+export declare function touchEveryMs(timeoutMs: number): number;
+/**
+ * Whether a session last active at `lastActivity` (epoch ms) has been idle
+ * past the limit. A session with no recorded activity — one signed in before
+ * the limit was set — is not expired; it starts counting now.
+ */
+export declare function idleExpired(lastActivity: unknown, now: number, timeoutMs: number): boolean;
+/** Whether the recorded activity should be written on this request. */
+export declare function shouldTouch(lastActivity: unknown, now: number, timeoutMs: number): boolean;
+/**
+ * The limit that applies to one person (#1546): the shortest positive value
+ * among the site setting and their roles' `idle-timeout-minutes`. A role can
+ * only shorten the site value, never lengthen it; 0 or absent means "no limit
+ * from here", so with nothing set anywhere the timeout stays off.
+ */
+export declare function effectiveIdleTimeoutMs(siteMinutes: unknown, roleMinutes?: readonly unknown[]): number;
+/** How long before sign-out the page warns: two minutes, or a quarter of a shorter limit. */
+export declare function warnBeforeMs(timeoutMs: number): number;
+/** What is left of the limit, never negative; null when no limit applies. */
+export declare function idleRemainingMs(lastActivity: unknown, now: number, timeoutMs: number): number | null;
+/** The status poll does not count as activity, or the warning would keep the session alive by itself. */
+export declare const IDLE_STATUS_PATH = "/api/session/idle-status";

package/lib/src/utils/sessionLimits.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Session limits (#1767): the absolute cap on a signed-in session, and how it
+ * sits beside the idle timeout (#1546, `sessionIdle.ts`).
+ *
+ * `ngdpbase.session.max-age` (milliseconds) is the longest a sign-in lasts:
+ * a signed-in session ends that long after it signed in, however active it
+ * has been. Shipped at 30 days; the idle timeout (7 days) usually ends a
+ * session first.
+ *
+ * Why it is enforced here and not by the cookie (found 2026-10-12, #1767):
+ * before this, `max-age` only set express-session's `cookie.maxAge` and the
+ * file store's `ttl`, and neither is a cap.
+ *
+ * - express-session (`rolling: false`, the default) re-issues the cookie with
+ *   a fresh expiry, now + maxAge, on every response whose session changed;
+ *   the app changes it often (CSRF token, IP capture, the idle timer's
+ *   last-activity write).
+ * - On every other request it calls the store's `touch()`, and
+ *   session-file-store rewrites `__lastAccess`; a stored session expires
+ *   `cookie.originalMaxAge` after its LAST access, not its first.
+ *
+ * So `max-age` was a rolling lifetime: a session in use never ended. The cap
+ * is now checked on every request from `signedInAt`, which only sign-in
+ * completion writes (`AuthManager.completeSignIn`, on the new session after
+ * regeneration); a re-authentication (step-up) does not move it.
+ *
+ * The cookie and the store keep their rolling behaviour and only have to be
+ * long enough: a signed-in session's cookie lives `max-age` from its last
+ * change (set at sign-in), so it never ends a session before the cap. An
+ * anonymous session (every visitor gets one, for the CSRF token) keeps the
+ * shorter `ngdpbase.session.anonymous-max-age`, so a 30-day cap does not keep a month of
+ * one-visit sessions in the store.
+ */
+/** The shipped `ngdpbase.session.max-age`: 30 days. */
+export declare const DEFAULT_SESSION_MAX_AGE_MS: number;
+/** The shipped `ngdpbase.session.anonymous-max-age`: a day, the old shipped `max-age`. */
+export declare const DEFAULT_ANONYMOUS_SESSION_MS: number;
+/**
+ * How long a session nobody signed in to lives after its last change:
+ * `ngdpbase.session.anonymous-max-age` (the shipped day when not a positive
+ * number), or the cap when that is shorter.
+ */
+export declare function anonymousSessionMs(capMs: number, configured?: unknown): number;
+/** The configured cap in milliseconds; the shipped 30 days when not a positive number. There is no "off". */
+export declare function sessionCapMs(value: unknown): number;
+/** Whether a session signed in at `signedInAt` (epoch ms) is past the cap. No recorded time is not expired. */
+export declare function capExpired(signedInAt: unknown, now: number, capMs: number): boolean;
+/** What one request does to a signed-in session. */
+export type SessionLimitVerdict = {
+    end: 'max-age' | 'idle-timeout';
+} | {
+    end: null;
+    stampSignedIn: boolean;
+    touch: boolean;
+};
+/**
+ * The per-request check of a signed-in session against both limits: the cap
+ * first (it holds whatever the activity), then the idle timeout. A session
+ * signed in before `signedInAt` was recorded starts its cap now
+ * (`stampSignedIn`), as the idle timer does for a missing last activity.
+ */
+export declare function checkSessionLimits(session: {
+    signedInAt?: unknown;
+    lastActivity?: unknown;
+}, now: number, limits: {
+    idleMs: number;
+    capMs: number;
+}): SessionLimitVerdict;