@jwilleke/ngdpbase-types 5.41.0 → 5.42.0

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

@@ -0,0 +1,71 @@
+/**
+ * Process lifecycle as audit events (#1149).
+ *
+ * Nothing recorded that an instance started or stopped, so an unclean exit was
+ * undetectable from the log. That matters because of #1148: on an unclean exit
+ * the buffered audit records are lost, the chain resumes from the last WRITTEN
+ * record at boot, verification passes, and nothing shows anything is absent.
+ * The log does not lie about the records it holds — it simply cannot say that
+ * records are missing.
+ *
+ * A `system-start` with no `system-shutdown` before it says exactly that. It
+ * cannot recover the lost records; it marks the window in which records may be
+ * absent, which is the difference between an audit trail with a known gap and
+ * one that quietly appears complete.
+ */
+import type { AuditEvent } from './auditEvents.js';
+/** What the previous run's ending can be established to be. */
+export type PreviousRun = 
+/** A shutdown was recorded after the last start. */
+'clean'
+/** A start was recorded with no shutdown after it. Records may be missing. */
+ | 'unclean'
+/** No start on record — a first boot, or history beyond the log. */
+ | 'none'
+/** The records present cannot establish an ordering. */
+ | 'unknown';
+/** The minimum of a stored record this assessment needs. */
+export interface LifecycleRecord {
+    timestamp?: string;
+}
+/**
+ * Decide how the previous run ended, from the latest record of each phase.
+ *
+ * Deliberately conservative in three places, because the whole value of this
+ * is that it does not overclaim:
+ *
+ * - No start on record is `none`, not `unclean`. A first boot must not accuse
+ *   itself, or every new instance cries wolf and the signal stops being read.
+ * - A shutdown with no start is `unknown`, not `clean`. That is only reachable
+ *   through a truncated or rotated log, and concluding "clean" from half the
+ *   evidence is the failure this exists to prevent.
+ * - Equal timestamps are `unclean`. Same-millisecond records cannot establish
+ *   ordering, so the shutdown did not *demonstrably* follow the start.
+ */
+export declare function assessPreviousRun(lastStart: LifecycleRecord | null, lastShutdown: LifecycleRecord | null): PreviousRun;
+export interface LifecycleEventInput {
+    /** The system principal (#631). Falls back to the literal only where no UserManager answers. */
+    principal?: string;
+    phase: 'start' | 'shutdown';
+    /** The running version, so a restart is distinguishable from an upgrade. */
+    version: string;
+    pid: number;
+    /** Required on a start, meaningless on a shutdown. */
+    previousRun?: PreviousRun;
+    /**
+     * The transport the instance actually bound (#1153).
+     *
+     * "This instance is serving HTTP" is a security fact, and the log had no
+     * record of it — only the version and pid.
+     */
+    scheme?: 'http' | 'https';
+}
+/**
+ * Build the audit event for a process starting or stopping.
+ *
+ * `previousRun` appears on a start only, following the rule `page-rename` and
+ * `token-mint` already use: a field present on every event is useless as a
+ * filter. A shutdown is a statement about itself and makes no claim about the
+ * past.
+ */
+export declare function buildLifecycleAuditEvent(input: LifecycleEventInput): AuditEvent;

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

@@ -9,3 +9,21 @@
  * Null when the header names neither a browser nor a device we know.
  */
 export declare function describeBrowser(userAgent: string | undefined): string | null;
+/**
+ * #1523 slice 1c — the browser and operating system a remembered browser's
+ * device key was issued to, from the User-Agent and the `Sec-CH-UA-Platform`
+ * client hint every Chromium browser sends. Families only ("Chrome",
+ * "Windows"), never versions, so an update keeps the browser remembered. No
+ * fingerprinting beyond what each request already carries (operator,
+ * 2026-10-04). Null when the browser or the system cannot be told: such a
+ * browser is never remembered.
+ */
+export interface BrowserIdentity {
+    browser: string;
+    os: string;
+    /** The `Sec-CH-UA-Platform` hint, unquoted; empty when the browser sent none. */
+    platform: string;
+}
+export declare function browserIdentity(userAgent: string | undefined, platformHint: string | undefined): BrowserIdentity | null;
+/** Whether two identities name the same browser on the same system, the hint included (both sent it, or neither). */
+export declare function sameBrowser(a: BrowserIdentity, b: BrowserIdentity): boolean;

package/lib/src/utils/browserDescription.js

@@ -26,3 +26,15 @@ export function describeBrowser(userAgent) {
         return `${browser} on ${device}`;
     return browser ?? device;
 }
+export function browserIdentity(userAgent, platformHint) {
+    const described = describeBrowser(userAgent);
+    const [browser, os] = described?.split(' on ') ?? [];
+    if (!browser || !os)
+        return null;
+    const platform = (platformHint ?? '').trim().replace(/^"|"$/g, '').slice(0, 40);
+    return { browser, os, platform };
+}
+/** Whether two identities name the same browser on the same system, the hint included (both sent it, or neither). */
+export function sameBrowser(a, b) {
+    return a.browser === b.browser && a.os === b.os && a.platform === b.platform;
+}

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

@@ -0,0 +1,50 @@
+/** One place private files are kept, and what to call it in a message. */
+export interface PrivateStorageRoot {
+    label: string;
+    path: string;
+}
+/** How a media folder overlaps a root: it is the root, holds it, or is inside it. */
+export type OverlapRelation = 'equals' | 'contains' | 'is inside';
+export interface MediaFolderOverlap {
+    folder: string;
+    /** 1-based position of the folder in `ngdpbase.media.folders`. */
+    position: number;
+    root: PrivateStorageRoot;
+    relation: OverlapRelation;
+}
+/** Minimal configuration surface, so tests need no live engine. */
+export interface StorageRootConfig {
+    getProperty(key: string, defaultValue: unknown): unknown;
+    getResolvedDataPath(key: string, defaultValue: string): string;
+}
+/**
+ * Where private files live: the vaults (shared folders' pages and files are
+ * the `shared-folders` container's vault, so they are in here), the legacy
+ * `private/` root a site may not have moved yet, the shared folders' key
+ * storage, and two places in attachment storage: the old private attachments
+ * the migration leaves behind and reads as a fallback, and the thumbnail cache,
+ * which holds thumbnails of vault images. Attachment paths are the ones
+ * BasicAttachmentProvider resolves.
+ */
+export declare function privateStorageRoots(config: StorageRootConfig): PrivateStorageRoot[];
+/**
+ * The real path of `p`, or of its nearest existing ancestor with the rest
+ * appended. `p` is not normalized first: `link/..` is the parent of where
+ * `link` points, not the directory holding `link` (#2195).
+ */
+export declare function realPathOf(p: string): string;
+/** Whether `child` is `parent` or under it; both already real paths. */
+export declare function isSameOrUnder(child: string, parent: string): boolean;
+/** How `folder` overlaps `root`, or null for no overlap. */
+export declare function overlapRelation(folder: string, root: string): OverlapRelation | null;
+/** The first private storage root `folder` overlaps, or null. */
+export declare function findMediaFolderOverlap(folder: string, roots: PrivateStorageRoot[], position?: number): MediaFolderOverlap | null;
+/** Each of `folders` that overlaps a root, with its position in the list. */
+export declare function findMediaFolderOverlaps(folders: string[], roots: PrivateStorageRoot[]): MediaFolderOverlap[];
+/**
+ * The message for a refused folder. It names the folder by its position and
+ * the kind of storage. It never echoes the folder: one inside a vault would
+ * name the vault's owner and id, and the message reaches admin notices and
+ * their email.
+ */
+export declare function describeMediaFolderOverlap(o: MediaFolderOverlap): string;

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

@@ -0,0 +1,73 @@
+/**
+ * Record the security posture at boot and compare it against the previous boot
+ * (#1156, D19 of docs/security-posture.md).
+ *
+ * `config-change` (#1150) audits every change made through `setProperty()`,
+ * which leaves two holes:
+ *
+ * - An `app-custom-config.json` edited __directly on disk__ never passes
+ *   through `setProperty()` and emits nothing.
+ * - The state an instance __started in__ is never stated, only its deltas.
+ *
+ * Recording the posture at every start closes the second. Comparing that record
+ * against the previous start's closes the first: a change made on disk, or
+ * while the process was stopped, shows up as a difference between two
+ * consecutive boots __even though nothing observed the edit itself__.
+ *
+ * This is not the self-scoring D20 rejects. The comparison is against this
+ * instance's own previous state, a fact it holds, rather than against a
+ * recommended value set nobody can define.
+ */
+import type { PostureGroup } from './securityPosture.js';
+/** What a secret ingredient records instead of its value. */
+export declare const SECRET_PLACEHOLDER = "[secret]";
+/** The posture as recorded: one flat map of ingredient to value. */
+export type FlatPosture = Record<string, unknown>;
+/**
+ * Flatten the grouped posture for recording.
+ *
+ * A secret records that it is __set__ and never what it is set to. An entry
+ * naming a key alongside its value would reintroduce the disclosure
+ * `ngdpbase.config.sensitive-values` (its `secret` entries) exists to prevent, by a different route and
+ * into a file with longer retention than the logs it already guards.
+ */
+export declare function flattenPosture(groups: readonly PostureGroup[]): FlatPosture;
+export interface PostureDiff {
+    /**
+     * False when there is no previous record to compare against.
+     *
+     * Kept separate from "nothing changed", because they are different facts and
+     * only one of them is reassuring.
+     */
+    comparable: boolean;
+    changed: Array<{
+        key: string;
+        from: unknown;
+        to: unknown;
+    }>;
+    added: string[];
+    removed: string[];
+}
+/**
+ * Compare the posture now against the posture at the previous boot.
+ *
+ * __No previous record is `comparable: false`, never "no change".__ Only the
+ * last 1000 log lines are loaded for search (`FileAuditProvider.ts:610`), so on
+ * a busy instance the previous boot's record can fall outside the window.
+ * Reporting that as "nothing changed" would be a false all-clear at exactly the
+ * moment an operator is relying on the check.
+ *
+ * An ingredient added to or removed from the __view__ is reported separately
+ * from a __value__ change: removing an ingredient changes nothing about what
+ * the instance does (D4, D16), and folding both into "posture changed" would
+ * lose the distinction that matters when reading the log back.
+ */
+export declare function diffPostures(previous: FlatPosture | null, current: FlatPosture): PostureDiff;
+/**
+ * The line an operator reads at startup.
+ *
+ * A difference found here says explicitly that nothing observed the edit —
+ * otherwise the obvious question is why it is being reported at boot rather
+ * than as a `config-change`, and the answer is the whole point.
+ */
+export declare function describePostureDiff(diff: PostureDiff): string;

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

@@ -155,6 +155,12 @@ export interface PrivatePageName {
  * also its URL. No account can be called this (`RESERVED_USERNAMES`).
  */
 export declare const SHARED_FOLDER_OWNER = "shared-folders";
+/**
+ * Whether `id` has the shape a store gives a file (`crypto.randomUUID()`), so
+ * a takeout's file can be stored under it again (#2188). Anything else, a
+ * path or a pool's content hash among them, is never reused as a file name.
+ */
+export declare function isRestorableFileId(id: string): boolean;
 /** A shared folder page's name, and its URL without the leading slash: `shared/{folder}/{title}`. */
 export declare const SHARED_PAGE_NAME_PREFIX = "shared/";
 /** The first path segment of a shared folder's URL: `/shared/{folder}/{title}`. */

package/lib/src/utils/privateStorePath.js

@@ -212,6 +212,14 @@ export const PRIVATE_SLUG_PREFIX = 'vaults--';
  * also its URL. No account can be called this (`RESERVED_USERNAMES`).
  */
 export const SHARED_FOLDER_OWNER = 'shared-folders';
+/**
+ * Whether `id` has the shape a store gives a file (`crypto.randomUUID()`), so
+ * a takeout's file can be stored under it again (#2188). Anything else, a
+ * path or a pool's content hash among them, is never reused as a file name.
+ */
+export function isRestorableFileId(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id);
+}
 /** A shared folder page's name, and its URL without the leading slash: `shared/{folder}/{title}`. */
 export const SHARED_PAGE_NAME_PREFIX = 'shared/';
 /** The first path segment of a shared folder's URL: `/shared/{folder}/{title}`. */

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

@@ -0,0 +1,52 @@
+/**
+ * The security posture — a view over the settings that determine what an
+ * instance guarantees (#1145).
+ *
+ * An operator cannot otherwise see what their instance's security settings
+ * are: they sit in `config/app-default-config.json` among some five hundred
+ * other keys, with nothing presenting them as one subject. One of them is
+ * where a gap becomes visible as it ships — `ngdpbase.auth.factors` offers
+ * only single factors, which is where the absence of MFA becomes a visible
+ * fact rather than tribal knowledge.
+ *
+ * __This is a view, not a resolution layer (D3).__ Every item is an ordinary
+ * key with its own shipped default, read by live code. The posture decides
+ * which settings are presented together and shows what each is currently set
+ * to. It adds no resolution step and changes no value on its own — which is
+ * also why removing an ingredient is safe: the key keeps whatever it is set
+ * to and the code keeps reading it, it simply stops being displayed (D4).
+ *
+ * See docs/security-posture.md.
+ */
+/** The shape of `ConfigurationManager.getProperty`. */
+export type ConfigReader = (key: string, fallback?: unknown) => unknown;
+export declare const POSTURE_KEY = "ngdpbase.security.posture";
+export interface PostureItem {
+    key: string;
+    /** The current value. Absent when the key is a declared secret. */
+    value?: unknown;
+    /** Whether a change takes effect only after a restart (D6). */
+    restart: boolean;
+    /**
+     * True when the key is named in `ngdpbase.config.sensitive-values` (its `secret` entries).
+     *
+     * Reported as present but masked rather than dropped: an operator who added
+     * it deserves to know it is set, and silently omitting it would make the
+     * section quietly incomplete.
+     */
+    secret: boolean;
+    /** A plain-words caution when the value, read with another setting, does not do what it seems to. */
+    note?: string;
+}
+export interface PostureGroup {
+    group: string;
+    items: PostureItem[];
+}
+/**
+ * Read the posture and each ingredient's current value.
+ *
+ * A malformed or absent posture yields nothing rather than throwing. This
+ * feeds an admin screen, and an operator who mistyped the object should get an
+ * empty section and a chance to fix it, not a page that fails to render.
+ */
+export declare function resolvePosture(read: ConfigReader): PostureGroup[];

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

@@ -0,0 +1,59 @@
+/**
+ * Serve HTTPS when a certificate and key are configured (#1153).
+ *
+ * There was no TLS path at all: `app.listen()` is plain HTTP and no cert or
+ * key key existed, so an operator holding a certificate had nowhere to put it.
+ * The concrete consequence was a security setting that could not be turned on
+ * safely — `ngdpbase.session.secure` ships `false` because a LAN instance on
+ * plain HTTP that set it `true` would issue cookies the browser refuses to
+ * send back and lock itself out of its own sessions.
+ *
+ * __A broken TLS configuration does not silently become HTTP.__ That is a
+ * transport downgrade: the operator configured TLS, believes traffic is
+ * encrypted, and it is in the clear. It takes #1152's survivable-failure path
+ * instead — the instance boots into maintenance mode, names the file that is
+ * wrong, and keeps `/admin` and `/login` reachable so it can be repaired
+ * without filesystem access.
+ *
+ * __Expiry is the deliberate exception.__ Node does not validate `notAfter`
+ * when building a server context; the client rejects the certificate instead.
+ * So an expired certificate still serves and is reported loudly. Falling back
+ * would downgrade the transport over a certificate that is merely stale, and
+ * blocking would take down an instance whose operator may be mid-renewal —
+ * while a stale certificate is already loudly visible to every client, which a
+ * silent downgrade is not.
+ */
+/** The shape of `ConfigurationManager.getProperty`. */
+export type ConfigReader = (key: string, fallback?: unknown) => unknown;
+export declare const TLS_CERT_KEY = "ngdpbase.server.tls.cert-file";
+export declare const TLS_KEY_KEY = "ngdpbase.server.tls.key-file";
+export type TlsResolution = 
+/** No certificate configured. The ordinary case; not a problem. */
+{
+    mode: 'http';
+}
+/** Usable. `expired` is true when the certificate's own validity has passed. */
+ | {
+    mode: 'https';
+    cert: Buffer;
+    key: Buffer;
+    expired: boolean;
+    expiresAt: string | null;
+}
+/** Configured and unusable. Takes the #1152 survivable-failure path. */
+ | {
+    mode: 'blocked';
+    reasons: string[];
+};
+/** Injectable so the classification is testable without real certificates. */
+export interface TlsDeps {
+    readFile?: (path: string) => Buffer;
+    createSecureContext?: (options: {
+        cert: Buffer;
+        key: Buffer;
+    }) => unknown;
+    now?: () => Date;
+    /** ISO expiry of the certificate, or null when it cannot be read. */
+    certExpiry?: (cert: Buffer) => string | null;
+}
+export declare function resolveTlsConfig(read: ConfigReader, deps?: TlsDeps): TlsResolution;

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

@@ -0,0 +1,4 @@
+/** Seal `plain` for `username`; returns `v1.<iv>.<ciphertext+tag>`, base64url. */
+export declare function sealTotpSecret(credentialsKey: string, username: string, plain: string): string;
+/** Open a sealed value for `username`; null when it is malformed, for someone else, or under another key. */
+export declare function openTotpSecret(credentialsKey: string, username: string, sealed: string): string | null;

package/lib/src/utils/totpSeedCipher.js

@@ -0,0 +1,45 @@
+/**
+ * Encryption for TOTP seeds in the credentials store (#421).
+ *
+ * The store signs every row with `NGDPBASE_CREDENTIALS_KEY` but keeps it
+ * readable; a TOTP seed is a shared secret, so a reader of the file must not
+ * get it. The seed is AES-256-GCM encrypted under a subkey derived from the
+ * same key by HKDF (decided on #1523, 2026-10-31), so there is no new key to
+ * back up. The account name is the associated data: a sealed seed copied onto
+ * another person's row does not open.
+ */
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+const INFO = 'ngdpbase totp seed v1';
+const PREFIX = 'v1';
+function subkey(credentialsKey) {
+    if (!credentialsKey)
+        throw new Error('A TOTP seed needs NGDPBASE_CREDENTIALS_KEY (#421)');
+    return Buffer.from(hkdfSync('sha256', credentialsKey, Buffer.alloc(0), INFO, 32));
+}
+/** Seal `plain` for `username`; returns `v1.<iv>.<ciphertext+tag>`, base64url. */
+export function sealTotpSecret(credentialsKey, username, plain) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', subkey(credentialsKey), iv);
+    cipher.setAAD(Buffer.from(username, 'utf8'));
+    const body = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final(), cipher.getAuthTag()]);
+    return `${PREFIX}.${iv.toString('base64url')}.${body.toString('base64url')}`;
+}
+/** Open a sealed value for `username`; null when it is malformed, for someone else, or under another key. */
+export function openTotpSecret(credentialsKey, username, sealed) {
+    const parts = sealed.split('.');
+    if (parts.length !== 3 || parts[0] !== PREFIX)
+        return null;
+    try {
+        const iv = Buffer.from(parts[1], 'base64url');
+        const body = Buffer.from(parts[2], 'base64url');
+        if (iv.length !== 12 || body.length < 16)
+            return null;
+        const decipher = createDecipheriv('aes-256-gcm', subkey(credentialsKey), iv);
+        decipher.setAAD(Buffer.from(username, 'utf8'));
+        decipher.setAuthTag(body.subarray(body.length - 16));
+        return Buffer.concat([decipher.update(body.subarray(0, body.length - 16)), decipher.final()]).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.41.0",
+  "version": "5.42.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -40,6 +40,7 @@
     "@types/markdown-it": "^14.2.0",
     "@types/multer": "^2.3.0",
     "@types/node": "^24.19.2",
+    "@types/qrcode": "^1.5.6",
     "better-sqlite3-multiple-ciphers": "^13.0.3",
     "dotenv": "^18.0.9",
     "express": "^5.3.0",
@@ -47,12 +48,14 @@
     "fast-xml-parser": "^5.11.2",
     "fs-extra": "^11.4.1",
     "ipaddr.js": "^2.5.0",
-    "jose": "^6.2.13",
+    "jose": "^6.2.14",
     "linkedom": "^0.18.14",
     "markdown-it": "^14.3.3",
     "minisearch": "7.2.0",
     "mmdb-lib": "^3.0.3",
     "multer": "^2.4.0",
+    "otpauth": "^9.5.2",
+    "qrcode": "^1.5.4",
     "rrule-temporal": "2.2.8",
     "tar": "^7.5.22",
     "temporal-polyfill": "1.0.6",

package/lib/src/providers/mediaFilenameDate.d.ts

@@ -1,22 +0,0 @@
-/**
- * Conservative filename → capture-date parser (#809, slice C of #807).
- *
- * Last-resort fallback used by media providers when a file carries no usable
- * EXIF/QuickTime capture date. Many devices encode the capture time in the
- * filename (e.g. `PXL_20260113_123414708.jpg`, `2026-04-03-IMG_4654.jpg`,
- * `Feb_20_2026_19_25_04.jpg`); without this, those files index with
- * `dateTimeOriginal: null` and sort only by file `mtime`.
- *
- * Design constraints (from the issue):
- *   - **Conservative** — only a small set of high-confidence, anchored patterns
- *     are accepted. Anything ambiguous returns `null`, and the caller then
- *     falls back to `mtime` and surfaces the file to admins.
- *   - **Distinguishable provenance** — the caller records that the resulting
- *     date came from the filename (`captureDateSource: 'filename'`), so a
- *     parsed date never masquerades as authoritative EXIF metadata.
- *
- * Returns a `"YYYY-MM-DD HH:MM:SS"` string (the exact shape produced by the
- * EXIF extractor, so it flows through sort/filter identically), or `null`.
- * A date-only match yields a `00:00:00` time.
- */
-export declare function parseDateFromFilename(filename: string): string | null;