@jwilleke/ngdpbase-types 5.41.1 → 5.42.0

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/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.1",
+  "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",