@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

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

@@ -0,0 +1,54 @@
+/**
+ * Recovery words to keep (#2144): the sheet an admin or a user downloads as a
+ * file or prints while their new words still wait to be confirmed, and the
+ * audit record of handing them out.
+ *
+ * One sheet for both sets of words: the shared folders' (SharedFolderManager)
+ * and a user's vault key (the store door, `privateStoreDoor.ts`). The words
+ * come only from the set still held for confirmation; once confirmed they are
+ * gone from the server and cannot be made again, so nothing here stores,
+ * caches or logs them. No key material is on the sheet.
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+import { type AuditEventSink } from './auditEvents.js';
+/** Whose words: the organization's shared folders', or a user's vault key. */
+export type RecoveryWordsSet = 'shared-folders' | 'store';
+/** How they left the page: a plain text file, or the print view. */
+export type RecoveryWordsExport = 'download' | 'print';
+/** Everything the sheet shows, for the text file and the print view alike. */
+export interface RecoveryWordsSheet {
+    title: string;
+    siteName: string;
+    siteUrl: string;
+    /** When the words were made, in the server's local time with its offset. */
+    made: string;
+    words: readonly string[];
+    purpose: string;
+    notStored: string;
+}
+/** `date` in the server's local time: `2026-10-30 05:28 (UTC-04:00)`. */
+export declare function serverLocalTime(date: Date): string;
+/** The sheet for `words` of `set`, made at `madeAt`, on the site named `siteName` at `siteUrl`. */
+export declare function recoveryWordsSheet(args: {
+    set: RecoveryWordsSet;
+    siteName: string;
+    siteUrl: string;
+    words: readonly string[];
+    madeAt: Date;
+}): RecoveryWordsSheet;
+/** The sheet as a plain text file: the site, when made, the numbered words, what they are for. */
+export declare function recoveryWordsText(sheet: RecoveryWordsSheet): string;
+/** The file name: the site's name and whose words, safe for any file system. */
+export declare function recoveryWordsFilename(siteName: string, set: RecoveryWordsSet): string;
+/**
+ * Record that `ctx` downloaded or opened to print the set `wordsId` of `set`
+ * (`recovery-words-export`, on-failure refuse): called before the words are
+ * sent, so a record that cannot be written sends nothing. Who, which set and
+ * how; never the words.
+ */
+export declare function recordRecoveryWordsExport(sink: AuditEventSink | null | undefined, ctx: ActorContext, what: {
+    set: RecoveryWordsSet;
+    wordsId: string;
+    how: RecoveryWordsExport;
+    store?: string;
+}): Promise<void>;

package/lib/src/utils/safeRedirect.js

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+/** Where a rejected target sends the browser instead. */
+const FALLBACK = '/';
+/**
+ * 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 function safeRedirect(target) {
+    if (typeof target !== 'string')
+        return FALLBACK;
+    const value = target.trim();
+    if (value === '')
+        return FALLBACK;
+    // Header injection: a raw CR or LF in a Location value is never legitimate.
+    if (/[\r\n]/.test(value))
+        return FALLBACK;
+    // Must be an absolute path on this site.
+    if (!value.startsWith('/'))
+        return FALLBACK;
+    // `//host` and `/\host` are both read as protocol-relative by browsers —
+    // the second because they normalise backslashes to forward slashes.
+    if (value.startsWith('//') || value.startsWith('/\\'))
+        return FALLBACK;
+    // A scheme cannot appear in a path-only target. Catches `/redirect?to=http://…`
+    // being handed on verbatim as well as odd encodings that reach us decoded.
+    if (value.includes('://'))
+        return FALLBACK;
+    return value;
+}
+export default safeRedirect;

package/lib/src/utils/sessionAccount.js

@@ -0,0 +1,55 @@
+/**
+ * Whether a signed-in session still belongs to its account (#1937, #1482).
+ *
+ * A session names its account by username, and a username outlives the
+ * account: deleted, the name is free for a new account. So a session is
+ * bound, at sign-in, to the account it signed in to (`accountCreatedAt`, the
+ * account's `createdAt`), and on every request, and in the store sweep, it is
+ * held to that account as it is now:
+ *
+ * - no account by that name: the account was deleted (`account-deleted`);
+ * - an account by that name that is not the one it signed in to (another
+ *   `createdAt`, or created after the session signed in): the account was
+ *   deleted and the name reused, also `account-deleted`;
+ * - the account is turned off (`isActive === false`): `account-disabled`;
+ * - the password changed since it signed in (#1482): `password-changed`.
+ *
+ * One rule, asked by the session middleware in `app.ts` and by
+ * `UserManager.endStaleSessions` at startup; the end goes through `endSession`.
+ */
+import { sessionIsCurrent } from './sessionGeneration.js';
+/** The value a session is bound to: the account's creation time, or '' for a record without one. */
+export function accountBindingOf(account) {
+    return typeof account?.createdAt === 'string' ? account.createdAt : '';
+}
+/**
+ * What one request (or the sweep) does to a signed-in session, given its
+ * account as stored now (null when there is none). `bind` is set on a session
+ * signed in before the binding existed that still belongs to its account: the
+ * caller writes it to `accountCreatedAt`, once.
+ */
+export function checkSessionAccount(stored, account) {
+    const session = stored;
+    if (!account)
+        return { end: 'account-deleted' };
+    const binding = accountBindingOf(account);
+    if (typeof session.accountCreatedAt === 'string') {
+        if (session.accountCreatedAt !== binding)
+            return { end: 'account-deleted' };
+    }
+    else if (createdAfter(account, session.signedInAt)) {
+        // Signed in before this account existed: it belonged to an earlier one of the same name.
+        return { end: 'account-deleted' };
+    }
+    if (account.isActive === false)
+        return { end: 'account-disabled' };
+    if (!sessionIsCurrent(session.sessionGeneration, account))
+        return { end: 'password-changed' };
+    return typeof session.accountCreatedAt === 'string' ? { end: null } : { end: null, bind: binding };
+}
+function createdAfter(account, signedInAt) {
+    if (typeof signedInAt !== 'number' || !Number.isFinite(signedInAt))
+        return false;
+    const created = typeof account.createdAt === 'string' ? Date.parse(account.createdAt) : NaN;
+    return Number.isFinite(created) && created > signedInAt;
+}

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

@@ -2,6 +2,7 @@ export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password
 export declare function endSession(engine: {
     getManager(name: string): unknown;
 }, session: {
+    id?: unknown;
     username?: unknown;
     privateStoreHandle?: unknown;
     pendingConnection?: unknown;

package/lib/src/utils/sessionEnd.js

@@ -0,0 +1,42 @@
+/**
+ * The one door for a signed-in session ending (#1626, #1670).
+ *
+ * Whatever ends it — the person signs out, the session idles out or reaches
+ * `ngdpbase.session.max-age` from its sign-in (#1767), a password
+ * change ends the account's other sessions, or someone signs in again on the
+ * same browser — goes through here, so two things can never be forgotten:
+ *
+ * - its unlocked private-store keys are zeroed and dropped (#1626), and
+ * - the end is recorded as `authentication-logout`, with who, from where and
+ *   why (#1670). Until this, only the idle timeout was recorded.
+ * - a choice to act for someone (`actingFor`, #1762) ends with it.
+ * - so do the form POSTs it kept for a fresh sign-in (#2176), by its `id`.
+ *
+ * An account deleted or turned off ends its sessions here too (#1937), with
+ * the reason `account-deleted` / `account-disabled`: on the session's next
+ * request (`checkSessionAccount`), and in the store when the account is
+ * closed (`UserManager.deleteUserSessions`) or at startup (`endStaleSessions`).
+ *
+ * An admin revoking another person's session is recorded separately as
+ * `session-revoke`, by the route that does it. A session that simply expires
+ * in the store has no hook to call this; its keys are swept (#1626).
+ */
+import { endSessionKeys } from './privateStoreUnlock.js';
+import logger from './logger.js';
+export function endSession(engine, session, reason, from) {
+    endSessionKeys(session?.privateStoreHandle);
+    // #1743: an outside identity waiting to be connected never outlives the session it waited in.
+    if (session)
+        delete session.pendingConnection;
+    // #1762 slice 4: nor does a choice to act for someone.
+    if (session)
+        delete session.actingFor;
+    // #2176: nor do the form POSTs it kept for a fresh sign-in.
+    if (typeof session?.id === 'string')
+        engine.getManager('AuthManager')?.dropStepUpReplays?.(session.id);
+    const username = typeof session?.username === 'string' && session.username ? session.username : null;
+    if (!username)
+        return; // nobody was signed in: nothing ended
+    const audit = engine.getManager('AuditManager');
+    void audit?.logAuthentication?.({ username, ipAddress: from.ipAddress, userAgent: from.userAgent, loginMethod: 'session' }, 'logout', reason).catch((err) => logger.warn(`[SESSION] Could not record the end of ${username}'s session (${reason}):`, err));
+}

package/lib/src/utils/sessionGeneration.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/** The account's current generation; 0 when it has never been raised. */
+export function sessionGenerationOf(user) {
+    const g = user?.sessionGeneration;
+    return typeof g === 'number' && Number.isInteger(g) && g >= 0 ? g : 0;
+}
+/** Raise the account's generation, in place, and return the new value. */
+export function bumpSessionGeneration(user) {
+    user.sessionGeneration = sessionGenerationOf(user) + 1;
+    return user.sessionGeneration;
+}
+/** Whether a session stamped with `stamped` still belongs to the account as it is now. */
+export function sessionIsCurrent(stamped, user) {
+    const s = typeof stamped === 'number' && Number.isInteger(stamped) && stamped >= 0 ? stamped : 0;
+    return s === sessionGenerationOf(user);
+}

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

@@ -39,3 +39,7 @@ export declare function warnBeforeMs(timeoutMs: number): number;
 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";
+/** #2193: nor does a page's poll for its step-up prompt, or a page left waiting would keep its session alive. */
+export declare const STEP_UP_STATUS_PATH = "/auth/reauth/status";
+/** Whether a request to `path` counts as the person's activity: every one but the polls above. */
+export declare function countsAsActivity(path: string): boolean;

package/lib/src/utils/sessionIdle.js

@@ -0,0 +1,72 @@
+/**
+ * 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 function idleTimeoutMs(minutes) {
+    return typeof minutes === 'number' && Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : 0;
+}
+/** How stale the recorded activity may get before it is written again. */
+export function touchEveryMs(timeoutMs) {
+    return Math.min(60_000, Math.floor(timeoutMs / 4));
+}
+/**
+ * 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 function idleExpired(lastActivity, now, timeoutMs) {
+    if (timeoutMs <= 0 || typeof lastActivity !== 'number' || !Number.isFinite(lastActivity))
+        return false;
+    return now - lastActivity > timeoutMs;
+}
+/** Whether the recorded activity should be written on this request. */
+export function shouldTouch(lastActivity, now, timeoutMs) {
+    if (timeoutMs <= 0)
+        return false;
+    if (typeof lastActivity !== 'number' || !Number.isFinite(lastActivity))
+        return true;
+    return now - lastActivity >= touchEveryMs(timeoutMs);
+}
+/**
+ * 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 function effectiveIdleTimeoutMs(siteMinutes, roleMinutes = []) {
+    const candidates = [siteMinutes, ...roleMinutes].map(idleTimeoutMs).filter(ms => ms > 0);
+    return candidates.length === 0 ? 0 : Math.min(...candidates);
+}
+/** How long before sign-out the page warns: two minutes, or a quarter of a shorter limit. */
+export function warnBeforeMs(timeoutMs) {
+    return Math.min(120_000, Math.floor(timeoutMs / 4));
+}
+/** What is left of the limit, never negative; null when no limit applies. */
+export function idleRemainingMs(lastActivity, now, timeoutMs) {
+    if (timeoutMs <= 0)
+        return null;
+    if (typeof lastActivity !== 'number' || !Number.isFinite(lastActivity))
+        return timeoutMs;
+    return Math.max(0, timeoutMs - (now - lastActivity));
+}
+/** The status poll does not count as activity, or the warning would keep the session alive by itself. */
+export const IDLE_STATUS_PATH = '/api/session/idle-status';
+/** #2193: nor does a page's poll for its step-up prompt, or a page left waiting would keep its session alive. */
+export const STEP_UP_STATUS_PATH = '/auth/reauth/status';
+/** Whether a request to `path` counts as the person's activity: every one but the polls above. */
+export function countsAsActivity(path) {
+    return path !== IDLE_STATUS_PATH && path !== STEP_UP_STATUS_PATH;
+}

package/lib/src/utils/sessionLimits.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+import { idleExpired, shouldTouch } from './sessionIdle.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The shipped `ngdpbase.session.max-age`: 30 days. */
+export const DEFAULT_SESSION_MAX_AGE_MS = 30 * DAY_MS;
+/** The shipped `ngdpbase.session.anonymous-max-age`: a day, the old shipped `max-age`. */
+export const DEFAULT_ANONYMOUS_SESSION_MS = DAY_MS;
+/**
+ * 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 function anonymousSessionMs(capMs, configured = DEFAULT_ANONYMOUS_SESSION_MS) {
+    const anonymousMs = typeof configured === 'number' && Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_ANONYMOUS_SESSION_MS;
+    return Math.min(anonymousMs, capMs);
+}
+/** The configured cap in milliseconds; the shipped 30 days when not a positive number. There is no "off". */
+export function sessionCapMs(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : DEFAULT_SESSION_MAX_AGE_MS;
+}
+/** Whether a session signed in at `signedInAt` (epoch ms) is past the cap. No recorded time is not expired. */
+export function capExpired(signedInAt, now, capMs) {
+    if (typeof signedInAt !== 'number' || !Number.isFinite(signedInAt))
+        return false;
+    return now - signedInAt > capMs;
+}
+/**
+ * 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 function checkSessionLimits(session, now, limits) {
+    if (capExpired(session.signedInAt, now, limits.capMs))
+        return { end: 'max-age' };
+    if (idleExpired(session.lastActivity, now, limits.idleMs))
+        return { end: 'idle-timeout' };
+    const stamped = typeof session.signedInAt === 'number' && Number.isFinite(session.signedInAt);
+    return { end: null, stampSignedIn: !stamped, touch: shouldTouch(session.lastActivity, now, limits.idleMs) };
+}

package/lib/src/utils/sessionSecurity.js

@@ -0,0 +1,122 @@
+/**
+ * resolveSessionSecurity — keep `session.secure` and `trust proxy` consistent (#1046).
+ *
+ * #1043 made the session cookie `secure` actually turn on in production. On
+ * every HTTPS deployment that terminates TLS upstream — Cloudflare, an ingress,
+ * a tunnel — that silently broke login:
+ *
+ *   1. `secure` resolves true, so express-session will only emit `Set-Cookie`
+ *      on a connection it believes is https.
+ *   2. `trust proxy` defaults to false, so Express reads the raw socket and
+ *      believes the connection is plain http. It is not wrong — the hop from
+ *      the proxy really is http; it simply has not been told to read
+ *      X-Forwarded-Proto.
+ *   3. No session cookie ever reaches the browser. Every following request
+ *      builds a fresh session, so `req.session.csrfToken` is missing and the
+ *      CSRF middleware answers `403 Forbidden — invalid CSRF token` — on
+ *      `POST /login` included. Nobody can sign in.
+ *
+ * The two settings are not independent, so they are resolved together here.
+ * Turning on `secure` without `trust proxy` is not a working configuration;
+ * `secure` is the operator's stated intent to be behind TLS, and behind
+ * terminated TLS `trust proxy` is what makes Express able to see it.
+ *
+ * The operator's explicit choice still wins for both keys. The shipped
+ * app-default-config.json pins `ngdpbase.session.secure` and
+ * `ngdpbase.server.trust-proxy` to false, so a plain getProperty() read cannot
+ * tell "operator asked for false" from "nobody has said anything" — hence
+ * reading getCustomProperties() rather than the merged view.
+ *
+ * ## #1160 — native TLS breaks the assumption
+ *
+ * All of the above assumed `secure: true` meant TLS terminated UPSTREAM, so a
+ * proxy existed whose `X-Forwarded-Proto` Express had to be told to read. #1153
+ * made the server able to terminate TLS itself, and then there is no proxy —
+ * and trusting a forwarded header that nothing sets is worse than not trusting
+ * it. With `trust proxy` on and nothing in front, a caller can assert their own
+ * address and scheme, which the login throttle counts by and the audit log
+ * records.
+ *
+ * So the derivation now asks what is actually true rather than inferring from
+ * `secure` alone. The same applies to the misconfiguration warning: `secure`
+ * with `trust-proxy` explicitly false is the CORRECT configuration under native
+ * TLS, and warning about it would train an operator to ignore a warning that is
+ * load-bearing in the upstream case.
+ */
+/** Config keys this resolution reads, spelled once. */
+const SECURE_KEY = 'ngdpbase.session.secure';
+const TRUST_PROXY_KEY = 'ngdpbase.server.trust-proxy';
+/**
+ * Resolve the session cookie's `secure` flag and the matching `trust proxy`.
+ *
+ * `secure`: the operator's explicit boolean, else on when NODE_ENV is
+ * production. Inferring it from the request would get the terminated-TLS case
+ * exactly backwards, which is the case that matters.
+ *
+ * `trustProxy`: the operator's explicit value, else `true` whenever `secure`
+ * ends up on. `true` — rather than a hop count — because req.ip must come out
+ * as the end client. Under `1` behind Cloudflare, req.ip would resolve to the
+ * edge address shared by every visitor, and the login throttle's `ip:` bucket
+ * (#1044) would lock out all users at once on ten failures from anyone. An
+ * operator whose instance is also reachable directly should pin a hop count or
+ * a subnet list, since X-Forwarded-For is client-spoofable on that path.
+ *
+ * @param customProperties operator overrides only — NOT the merged config
+ * @param nodeEnv typically process.env.NODE_ENV
+ */
+export function resolveSessionSecurity(customProperties, nodeEnv, context = {}) {
+    const custom = customProperties ?? {};
+    const nativeTls = context.nativeTls === true;
+    const customSecure = custom[SECURE_KEY];
+    const secure = typeof customSecure === 'boolean'
+        ? customSecure
+        : nodeEnv === 'production';
+    const customTrustProxy = custom[TRUST_PROXY_KEY];
+    const trustProxyConfigured = typeof customTrustProxy === 'boolean' ||
+        typeof customTrustProxy === 'number' ||
+        typeof customTrustProxy === 'string';
+    if (trustProxyConfigured) {
+        const trustProxy = customTrustProxy;
+        return {
+            secure,
+            trustProxy,
+            trustProxyDerived: false,
+            // #1160: under native TLS this combination is CORRECT, not suspicious —
+            // the server is the TLS endpoint and there is no proxy whose headers to
+            // read. Warning about it would train an operator to ignore a warning
+            // that is load-bearing when TLS really is terminated upstream.
+            misconfigured: secure && trustProxy === false && !nativeTls
+        };
+    }
+    // #1160: only derive when something in FRONT is terminating TLS. With native
+    // TLS there is no proxy, and trusting a forwarded header that nothing sets
+    // lets a caller assert their own address and scheme — which the login
+    // throttle counts by and the audit log records.
+    const derive = secure && !nativeTls;
+    return {
+        secure,
+        trustProxy: derive ? true : false,
+        trustProxyDerived: derive,
+        misconfigured: false
+    };
+}
+/**
+ * #2071 — what an administrator and a visitor are told when the session
+ * cookie cannot reach the browser, spelled once: the server log, the admin
+ * dashboard, the CSRF refusal and the login page all say this.
+ */
+export const SESSION_COOKIE_WITHHELD_MESSAGE = 'Sign-in cannot work on this connection: this site sends its session cookie only over https, ' +
+    'and this request came over plain http, so the browser never receives it. ' +
+    'Serve the site over https, put it behind a proxy that sets X-Forwarded-Proto, ' +
+    'or set ngdpbase.session.secure to false.';
+/**
+ * True when express-session will NOT send the session cookie on this request
+ * (#2071): the cookie is `secure` and the request is not https as Express
+ * sees it, after `trust proxy`. express-session makes exactly this check and
+ * then silently sends nothing, so the browser has no session, every POST
+ * meets a fresh one, and the CSRF middleware refuses it. A boolean read of
+ * two fields, cheap enough for every request.
+ */
+export function sessionCookieWithheld(req) {
+    return req.session?.cookie?.secure === true && req.secure !== true;
+}

package/lib/src/utils/shareLockbox.js

@@ -0,0 +1,101 @@
+/**
+ * Lockboxes for links to encrypted vaults (#1388).
+ *
+ * A link to an encrypted vault is `/share/{token}#{key}`. The part after `#`
+ * is the link's private key; browsers never send it, so the server never sees
+ * it. The key pair is made in the owner's browser, which sends the server
+ * only the public half (`LinkPublicKey`).
+ *
+ * The server prepares each covered page, and the files it uses, and locks
+ * them for that public key: a {@link Lockbox}. It can lock, never open. The
+ * recipient's browser opens each lockbox with the private key from the link.
+ *
+ * The algorithm is WebCrypto's own, so the server (Node's `crypto.webcrypto`)
+ * and the browser (`window.crypto.subtle`, public/share/_assets/share-viewer.js) run the
+ * same steps: ECDH on P-256 between a fresh ephemeral key and the link's key,
+ * HKDF-SHA-256 over the shared secret, AES-256-GCM over the content.
+ */
+import { webcrypto } from 'crypto';
+const subtle = webcrypto.subtle;
+const CURVE = 'P-256';
+/** The HKDF salt and info; a lockbox of another version will not open with this one. */
+const HKDF_LABEL = new TextEncoder().encode('ngdp-share-lockbox-v1');
+const B64URL = /^[A-Za-z0-9_-]+$/;
+/**
+ * The public key a browser sent, checked strictly: a P-256 point and nothing
+ * else. Anything malformed is refused rather than stored.
+ */
+export function parseLinkPublicKey(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (v.kty !== 'EC' || v.crv !== CURVE)
+        return null;
+    if (typeof v.x !== 'string' || typeof v.y !== 'string' || !B64URL.test(v.x) || !B64URL.test(v.y))
+        return null;
+    // A P-256 coordinate is 32 bytes: 43 base64url characters.
+    if (v.x.length !== 43 || v.y.length !== 43)
+        return null;
+    if ('d' in v)
+        return null;
+    return { kty: 'EC', crv: CURVE, x: v.x, y: v.y };
+}
+async function importPublic(key) {
+    return subtle.importKey('jwk', { ...key, ext: true }, { name: 'ECDH', namedCurve: CURVE }, true, []);
+}
+async function contentKey(privateKey, publicKey, usage) {
+    const shared = await subtle.deriveBits({ name: 'ECDH', public: publicKey }, privateKey, 256);
+    const hkdf = await subtle.importKey('raw', shared, 'HKDF', false, ['deriveKey']);
+    return subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: HKDF_LABEL, info: HKDF_LABEL }, hkdf, { name: 'AES-GCM', length: 256 }, false, [usage]);
+}
+/** Lock `plaintext` for the link whose public key is `linkKey`. Only that link's private key opens it. */
+export async function sealForLink(linkKey, plaintext) {
+    const ephemeral = await subtle.generateKey({ name: 'ECDH', namedCurve: CURVE }, true, ['deriveBits']);
+    const key = await contentKey(ephemeral.privateKey, await importPublic(linkKey), 'encrypt');
+    const iv = webcrypto.getRandomValues(new Uint8Array(12));
+    const ct = new Uint8Array(await subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext));
+    const epk = await subtle.exportKey('jwk', ephemeral.publicKey);
+    return {
+        v: 1,
+        epk: { kty: 'EC', crv: CURVE, x: String(epk.x), y: String(epk.y) },
+        iv: Buffer.from(iv).toString('base64url'),
+        ct: Buffer.from(ct).toString('base64url')
+    };
+}
+/**
+ * The key part of a link, `{d}.{x}.{y}` in base64url: the private key the
+ * owner's browser made. The server never holds one; this is for the tests,
+ * and mirrors what the viewer does.
+ */
+export function linkKeyFromParts(jwk) {
+    return `${jwk.d}.${jwk.x}.${jwk.y}`;
+}
+/**
+ * Make a key pair on the server. A link's pair is made in the owner's browser,
+ * so for links this is the tests' stand-in; a person's own key pair for proxy
+ * access (#1762 slice 5, `privateStoreCrypto.newPersonKey`) is made here.
+ */
+export async function newLinkKeyPair() {
+    const pair = await subtle.generateKey({ name: 'ECDH', namedCurve: CURVE }, true, ['deriveBits']);
+    const jwk = await subtle.exportKey('jwk', pair.privateKey);
+    return {
+        publicKey: { kty: 'EC', crv: CURVE, x: String(jwk.x), y: String(jwk.y) },
+        linkKey: linkKeyFromParts({ d: String(jwk.d), x: String(jwk.x), y: String(jwk.y) })
+    };
+}
+/** Open a lockbox with a link's key, as the recipient's browser does. */
+export async function openLockbox(linkKey, box) {
+    const [d, x, y] = linkKey.split('.');
+    if (!d || !x || !y)
+        throw new Error('not a link key');
+    const privateKey = await subtle.importKey('jwk', { kty: 'EC', crv: CURVE, d, x, y, ext: true }, { name: 'ECDH', namedCurve: CURVE }, false, ['deriveBits']);
+    const key = await contentKey(privateKey, await importPublic(box.epk), 'decrypt');
+    return new Uint8Array(await subtle.decrypt({ name: 'AES-GCM', iv: Buffer.from(box.iv, 'base64url') }, key, Buffer.from(box.ct, 'base64url')));
+}
+/** True when `value` has the shape of a stored lockbox. */
+export function isLockbox(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return v.v === 1 && typeof v.iv === 'string' && typeof v.ct === 'string' && parseLinkPublicKey(v.epk) !== null;
+}