@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,74 @@
+/**
+ * The configuration files: where they are, how they are read, and how the
+ * custom file merges over the shipped one (#1214).
+ *
+ * One implementation, used by `ConfigurationManager` after the engine exists
+ * and by `app.ts` before it does (the listen port, TLS at bind time, and the
+ * base-URL explicitness check all run before `engine.initialize()`). Until
+ * #1214 `app.ts` had its own copy: a shallow spread that replaced a whole map
+ * on override, kept `_comment` keys, and computed the paths a second and third
+ * time. It happened to agree with the manager only because the keys it read
+ * were scalars.
+ *
+ * What stays in the manager: the legacy-key migrations (#642, #1117). They
+ * log, and they run between reading and merging. A pre-engine read therefore
+ * does not see a base URL set under a legacy key; that is a known limit named
+ * in the issue, not a second rule.
+ */
+export declare const DEFAULT_CONFIG_FILE = "app-default-config.json";
+export declare const DEFAULT_CUSTOM_CONFIG_FILE = "app-custom-config.json";
+type Env = Record<string, string | undefined>;
+/**
+ * The marker the setup wizard (or a headless install) writes when a site is
+ * installed. Its presence alone says the site is installed (#1410).
+ */
+export declare function installCompletePath(dataFolder: string): string;
+/** Fast-storage data folder: FAST_STORAGE, then the legacy INSTANCE_DATA_FOLDER, then ./data. */
+export declare function instanceDataFolder(env?: Env): string;
+export interface ConfigFilePaths {
+    instanceDataFolder: string;
+    /** The shipped defaults, in the code checkout: ./config/app-default-config.json */
+    defaultConfigPath: string;
+    /** The instance's overrides: <instanceDataFolder>/config/<INSTANCE_CONFIG_FILE or app-custom-config.json> */
+    customConfigPath: string;
+}
+/** The one derivation of both paths. */
+export declare function configFilePaths(env?: Env, cwd?: string): ConfigFilePaths;
+export interface ConfigFiles {
+    /** Null when the shipped file is missing — the caller decides whether that is fatal. */
+    defaultConfig: Record<string, unknown> | null;
+    /** The custom file with `_`-prefixed comment keys dropped; empty when the file is absent. */
+    customConfig: Record<string, unknown>;
+    /** The keys the operator set themselves, for "explicit or inherited?" questions (#1163). */
+    customKeys: Set<string>;
+    customConfigFound: boolean;
+}
+/** Read both files. Synchronous: both callers run at boot, before anything is served. */
+export declare function readConfigFilesSync(paths: ConfigFilePaths): ConfigFiles;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Merge two arrays.
+ *
+ * If both hold objects that share an identity field (`id`, `authproviderid`),
+ * merge by it: a later entry overrides the same one and adds new ones.
+ * Otherwise the custom array replaces the default entirely — which is why a set
+ * an operator or an add-on may extend one entry at a time is a map, never an
+ * array (#1612).
+ */
+export declare function mergeArrays(defaultArray: unknown[], customArray: unknown[]): unknown[];
+/** The entries of a set: a map's `true` keys, in order; a legacy array's strings. Anything else is empty. */
+export declare function enabledEntries(value: unknown): string[];
+/**
+ * Deep merge, custom over default.
+ *
+ * - plain objects: recursively, key by key
+ * - arrays: {@link mergeArrays}
+ * - an array of names onto a set map: the names are added (#1612)
+ * - `null`: an explicit removal — the custom file cannot express a deletion any other way
+ * - `undefined`: skipped
+ * - anything else: custom wins
+ */
+export declare function deepMergeObjects(defaultObj: Record<string, unknown>, customObj: Record<string, unknown>): Record<string, unknown>;
+/** The top-level merge is the same rule; the name records what the two inputs are. */
+export declare function deepMergeConfigs<T extends Record<string, unknown>>(defaultConfig: T, customConfig: Partial<T>): T;
+export {};

package/lib/src/utils/configFiles.js

@@ -0,0 +1,150 @@
+/**
+ * The configuration files: where they are, how they are read, and how the
+ * custom file merges over the shipped one (#1214).
+ *
+ * One implementation, used by `ConfigurationManager` after the engine exists
+ * and by `app.ts` before it does (the listen port, TLS at bind time, and the
+ * base-URL explicitness check all run before `engine.initialize()`). Until
+ * #1214 `app.ts` had its own copy: a shallow spread that replaced a whole map
+ * on override, kept `_comment` keys, and computed the paths a second and third
+ * time. It happened to agree with the manager only because the keys it read
+ * were scalars.
+ *
+ * What stays in the manager: the legacy-key migrations (#642, #1117). They
+ * log, and they run between reading and merging. A pre-engine read therefore
+ * does not see a base URL set under a legacy key; that is a known limit named
+ * in the issue, not a second rule.
+ */
+import fs from 'fs';
+import path from 'path';
+export const DEFAULT_CONFIG_FILE = 'app-default-config.json';
+export const DEFAULT_CUSTOM_CONFIG_FILE = 'app-custom-config.json';
+/**
+ * The marker the setup wizard (or a headless install) writes when a site is
+ * installed. Its presence alone says the site is installed (#1410).
+ */
+export function installCompletePath(dataFolder) {
+    return path.join(dataFolder, '.install-complete');
+}
+/** Fast-storage data folder: FAST_STORAGE, then the legacy INSTANCE_DATA_FOLDER, then ./data. */
+export function instanceDataFolder(env = process.env) {
+    return env.FAST_STORAGE || env.INSTANCE_DATA_FOLDER || './data';
+}
+/** The one derivation of both paths. */
+export function configFilePaths(env = process.env, cwd = process.cwd()) {
+    const dataFolder = instanceDataFolder(env);
+    return {
+        instanceDataFolder: dataFolder,
+        defaultConfigPath: path.join(cwd, 'config', DEFAULT_CONFIG_FILE),
+        customConfigPath: path.join(dataFolder, 'config', env.INSTANCE_CONFIG_FILE || DEFAULT_CUSTOM_CONFIG_FILE)
+    };
+}
+/** Read both files. Synchronous: both callers run at boot, before anything is served. */
+export function readConfigFilesSync(paths) {
+    const defaultConfig = fs.existsSync(paths.defaultConfigPath)
+        ? JSON.parse(fs.readFileSync(paths.defaultConfigPath, 'utf8'))
+        : null;
+    const customConfig = {};
+    const customConfigFound = fs.existsSync(paths.customConfigPath);
+    if (customConfigFound) {
+        const raw = JSON.parse(fs.readFileSync(paths.customConfigPath, 'utf8'));
+        for (const [key, value] of Object.entries(raw)) {
+            if (!key.startsWith('_'))
+                customConfig[key] = value;
+        }
+    }
+    return { defaultConfig, customConfig, customKeys: new Set(Object.keys(customConfig)), customConfigFound };
+}
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The fields that identify an entry in a list of objects: `id`, or
+ * `authproviderid` for `ngdpbase.auth.factors` (#1523, #1612).
+ */
+const IDENTITY_FIELDS = ['id', 'authproviderid'];
+function identityField(arr) {
+    if (arr.length === 0)
+        return null;
+    for (const field of IDENTITY_FIELDS) {
+        if (arr.every((e) => isPlainObject(e) && typeof e[field] === 'string'))
+            return field;
+    }
+    return null;
+}
+/**
+ * Merge two arrays.
+ *
+ * If both hold objects that share an identity field (`id`, `authproviderid`),
+ * merge by it: a later entry overrides the same one and adds new ones.
+ * Otherwise the custom array replaces the default entirely — which is why a set
+ * an operator or an add-on may extend one entry at a time is a map, never an
+ * array (#1612).
+ */
+export function mergeArrays(defaultArray, customArray) {
+    const field = identityField(defaultArray);
+    if (field && identityField(customArray) === field) {
+        const merged = new Map();
+        for (const item of defaultArray)
+            merged.set(item[field], item);
+        for (const item of customArray)
+            merged.set(item[field], item);
+        return Array.from(merged.values());
+    }
+    return customArray;
+}
+/**
+ * A set kept as a map of entry → `true` (#1612): any layer — an add-on, the
+ * operator — adds an entry without restating the rest, and `false` removes one
+ * on the record. An array merged onto such a map adds its entries rather than
+ * replacing the map, so a layer written as a list (an older custom config, an
+ * add-on) still extends the set.
+ */
+function isEntryMap(value) {
+    return isPlainObject(value)
+        && Object.keys(value).length > 0
+        && Object.values(value).every((v) => typeof v === 'boolean' || v === null);
+}
+/** The entries of a set: a map's `true` keys, in order; a legacy array's strings. Anything else is empty. */
+export function enabledEntries(value) {
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (isPlainObject(value))
+        return Object.entries(value).filter(([, v]) => v === true).map(([k]) => k);
+    return [];
+}
+/**
+ * Deep merge, custom over default.
+ *
+ * - plain objects: recursively, key by key
+ * - arrays: {@link mergeArrays}
+ * - an array of names onto a set map: the names are added (#1612)
+ * - `null`: an explicit removal — the custom file cannot express a deletion any other way
+ * - `undefined`: skipped
+ * - anything else: custom wins
+ */
+export function deepMergeObjects(defaultObj, customObj) {
+    const result = { ...defaultObj };
+    for (const key of Object.keys(customObj)) {
+        const customValue = customObj[key];
+        const defaultValue = result[key];
+        if (customValue === undefined)
+            continue;
+        else if (customValue === null)
+            result[key] = customValue;
+        else if (Array.isArray(customValue) && Array.isArray(defaultValue))
+            result[key] = mergeArrays(defaultValue, customValue);
+        else if (Array.isArray(customValue) && isEntryMap(defaultValue) && customValue.every((e) => typeof e === 'string')) {
+            result[key] = { ...defaultValue, ...Object.fromEntries(customValue.map((e) => [e, true])) };
+        }
+        else if (isPlainObject(customValue) && isPlainObject(defaultValue))
+            result[key] = deepMergeObjects(defaultValue, customValue);
+        else
+            result[key] = customValue;
+    }
+    return result;
+}
+/** The top-level merge is the same rule; the name records what the two inputs are. */
+export function deepMergeConfigs(defaultConfig, customConfig) {
+    return deepMergeObjects(defaultConfig, customConfig);
+}

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

@@ -0,0 +1,48 @@
+/**
+ * What a delegated credential may never carry (#946, #1198, #1576).
+ *
+ * A person delegates a subset of their own permissions to something acting
+ * for them: an agent token they mint, or an app they allow through the OpenID
+ * Connect provider. Two kinds of permission are never delegable, however
+ * privileged the person:
+ *
+ * - `admin-*` — administration stays with a person at the keyboard
+ *   (#946 decision 3);
+ * - `token-mint` — a delegation never creates a standing credential, or a
+ *   leaked one could breed (#1198);
+ * - `token-extend` — a delegation never lengthens a standing credential, or a
+ *   leaked token could keep itself alive (#1734). Step-up already refuses it
+ *   to a delegation, but a site may turn step-up off; this does not move;
+ * - `proxy-grant` — a token or an app never lets someone act for the person
+ *   (#1762). A proxy grant itself may carry it (that is how a proxy passes
+ *   access on), so this rule is for tokens and apps, not proxy grants;
+ * - `vault-proxy` — it means something only inside a proxy grant, where it
+ *   lets the proxy into the person's vaults (#1762 slice 2); on a token or an
+ *   app it would read as access it can never give.
+ *
+ * One rule for both delegations, so they cannot drift.
+ */
+/** Actions a delegation may never carry, by prefix. */
+export declare const FORBIDDEN_DELEGATED_PREFIX = "admin-";
+/** The permission to mint a token — never carried by a delegation. */
+export declare const MINT_PERMISSION = "token-mint";
+/** The permission to extend a token — never carried by a delegation (#1734). */
+export declare const EXTEND_PERMISSION = "token-extend";
+/** The permission to make a proxy grant — never carried by a token or an app (#1762). */
+export declare const PROXY_GRANT_PERMISSION = "proxy-grant";
+/** The proxy grant's vault marker — never carried by a token or an app (#1762). */
+export declare const VAULT_PROXY_PERMISSION = "vault-proxy";
+/** Why a scope cannot be delegated, or null when it can. */
+export declare function refusedDelegatedScope(scope: string): string | null;
+/**
+ * A delegation's permission list as given (#946, #1762): at least one, each a
+ * non-empty string, de-duplicated in order. Throws a caller-safe message. One
+ * rule for agent tokens and proxy grants.
+ */
+export declare function requireScopeList(scopes: unknown): string[];
+/**
+ * "Delegate, not grant" (#1178, #1762): the scopes the delegator does not hold,
+ * in order. Empty means every scope is theirs to hand on. `holds` is asked of
+ * the policy decision point; with no answer there is no delegation.
+ */
+export declare function lackingScopes(scopes: readonly string[], holds: (scope: string) => Promise<boolean>): Promise<string[]>;

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

@@ -0,0 +1,21 @@
+/**
+ * Derive a username from an email address (#1026).
+ *
+ * Extracted from GoogleOIDCProvider so every auto-provisioning path — OIDC and
+ * magic link — produces the same username for the same address. Two rules that
+ * disagree would let one provider create `jim-smith` and the other `jimsmith`
+ * for the same person.
+ */
+import type UserManager from '../managers/UserManager.js';
+/**
+ * Turn an email address into an unused username.
+ *
+ * Local part, lowercased, with anything outside `[a-z0-9]` replaced by a
+ * hyphen; a numeric suffix is appended until the name is free.
+ *
+ * The result is only free as of this call — a caller that derives a name and
+ * creates the account later must be prepared for `createUser` to reject a
+ * duplicate that appeared in between.
+ */
+export declare function deriveUsername(email: string, userManager: UserManager): Promise<string>;
+export default deriveUsername;

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

@@ -0,0 +1,123 @@
+/** Why a path is, or is not, in the index. */
+export type MediaPathVerdict = 
+/** Present in the index under this exact path. */
+'indexed'
+/** Folded into another item by the #515 alternate-format dedup. */
+ | 'alternate'
+/** Outside every configured scan folder. */
+ | 'not-in-scanned-folder'
+/** Name begins with a dot. */
+ | 'dotfile'
+/** Extension is not in the configured set. */
+ | 'extension'
+/** A path segment matches `ignoreDirs`. */
+ | 'ignore-dir'
+/** Deeper than `maxDepth` below its scan root. */
+ | 'max-depth'
+/** Matched a `.ngdpbaseignore` pattern — the file's own or an ancestor's. */
+ | 'ignore-pattern'
+/** Carries the `ngdpbaseignore` EXIF/XMP keyword. */
+ | 'ignore-keyword'
+/** Eligible, but not in the index — most likely never scanned. */
+ | 'eligible-not-indexed';
+/**
+ * The subset of {@link MediaPathVerdict} that means "the scanner skipped this"
+ * (#1056). `indexed`, `alternate` and `eligible-not-indexed` are states rather
+ * than skips, so they are excluded.
+ *
+ * Shared with the scan-time skip report so the probe and the report cannot
+ * disagree about why a file is missing. Two vocabularies for one question is
+ * the drift this taxonomy exists to prevent.
+ */
+export type MediaSkipReason = Extract<MediaPathVerdict, 'not-in-scanned-folder' | 'dotfile' | 'extension' | 'ignore-dir' | 'max-depth' | 'ignore-pattern' | 'ignore-keyword'>;
+/** One file or directory the scanner passed over, and why. */
+export interface SkippedEntry {
+    /** Absolute path. For a directory-level skip, the directory itself. */
+    path: string;
+    reason: MediaSkipReason;
+    /** True when `path` is a directory whose contents were never walked. */
+    isDirectory?: boolean;
+    /** The pattern or directory name that matched, when there was one. */
+    matched?: string;
+}
+/**
+ * The persisted skip report for the most recent scan (#1056).
+ *
+ * `totalSkipped` is always exact; `skipped` may be capped, in which case
+ * `truncated` is true. Reporting a shortened list as if it were complete is the
+ * failure this shape exists to prevent — "0 excluded" while a directory-level
+ * ignore quietly dropped a whole tree is what made the original counter
+ * useless.
+ */
+export interface MediaSkipReport {
+    version: number;
+    /** ISO timestamp of the scan that produced it. */
+    scannedAt: string;
+    totalSkipped: number;
+    truncated: boolean;
+    /**
+     * Exact count per reason, never capped.
+     *
+     * Measured on the reference library, the capped list alone would have been
+     * close to useless: 14,746 skips, 14,714 of them `extension`, against a cap
+     * of 1,000. The list gives examples; these counts give the shape, and the
+     * shape is what tells an operator whether their file is one of 14,000
+     * sidecars or the single odd case.
+     */
+    byReason: Partial<Record<MediaSkipReason, number>>;
+    /**
+     * Exact count per matched value within a reason — extensions, ignored
+     * directory names, ignore patterns. Answers "is my .orf being dropped?"
+     * without needing the file to appear in the capped list at all.
+     *
+     * Entries with no `matched` (dotfiles) are absent by construction.
+     */
+    byMatched: Record<string, number>;
+    skipped: SkippedEntry[];
+}
+export interface MediaPathExplanation {
+    verdict: MediaPathVerdict;
+    /** One sentence an operator can act on. */
+    detail: string;
+    /** Index id, when the path resolves to an item. */
+    itemId?: string;
+    /** For `alternate`, the primary item this file was folded into. */
+    primaryPath?: string;
+    /** For `ignore-dir` / `ignore-pattern`, what actually matched. */
+    matched?: string;
+}
+/** What the classifier needs to know. Mirrors FileSystemMediaProviderConfig. */
+export interface MediaPathRules {
+    /** Absolute scan roots. */
+    folders: string[];
+    /** Directory names skipped anywhere in the tree. */
+    ignoreDirs: string[];
+    /** 0 = unlimited. Depth is counted below the scan root. */
+    maxDepth: number;
+    /** Lowercase, no leading dot. */
+    extensions: Set<string>;
+}
+/** Index facts, resolved by the caller so this stays free of I/O. */
+export interface MediaPathIndexFacts {
+    /** Item id when this exact path is indexed. */
+    indexedId?: string;
+    /** Set when the path is an alternate folded into another item. */
+    alternateOf?: {
+        id: string;
+        filePath: string;
+    };
+    /** `.ngdpbaseignore` pattern that matched, if the caller found one. */
+    ignorePatternMatch?: string;
+    /** True when the file carries the `ngdpbaseignore` EXIF/XMP keyword. */
+    hasIgnoreKeyword?: boolean;
+}
+/** Longest configured folder containing `target`, or null. */
+export declare function scanRootFor(target: string, folders: string[]): string | null;
+/**
+ * Classify one absolute path.
+ *
+ * Evaluated in scanner order. The caller supplies index facts and any
+ * `.ngdpbaseignore` match, because those need I/O and this deliberately does
+ * none — which is what makes every branch testable without a filesystem.
+ */
+export declare function explainMediaPath(target: string, rules: MediaPathRules, facts?: MediaPathIndexFacts): MediaPathExplanation;

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

@@ -0,0 +1,69 @@
+/**
+ * Former-title tracking for renamed pages (#1105).
+ *
+ * A rename leaves every inbound link pointing at a name that no longer exists.
+ * `rewriteInboundLinksAfterRename` repairs the links *inside* pages, but it is
+ * structurally unable to help a bookmark, a search result, or a link on someone
+ * else's site — those are not ours to rewrite.
+ *
+ * The record therefore lives in the page's own frontmatter:
+ *
+ * ```yaml
+ * title: New Title
+ * formerTitles:
+ *   - Old Title
+ * ```
+ *
+ * The page is its own durable record. No sidecar to drift from the pages it
+ * describes, no retention window to expire, and it survives backup/restore,
+ * export/import and a full index rebuild — because it *is* the data rather than
+ * a cache of it. This replaced an earlier design that rehydrated from
+ * `page-rename` audit events, which carry a 90-day retention: a page renamed and
+ * then left alone would have had its old URL start failing again months later,
+ * silently.
+ *
+ * Two rules carried over from the rename map this supersedes (#1082):
+ *
+ * **Consulted only after live resolution fails.** The caller tries the real page
+ * set first, so a former title can never shadow an existing page.
+ *
+ * **Ambiguity is refused, never guessed.** If one former title is claimed by more
+ * than one page, no answer is given. A confidently wrong redirect to a page that
+ * merely once shared a name is worse than the 404 it replaces, because a 404 is
+ * visibly broken and a wrong page is not.
+ */
+/** Sentinel for a former title claimed by more than one page. */
+export declare const AMBIGUOUS: unique symbol;
+/** Minimal page shape needed to derive the index. */
+export interface FormerTitleSource {
+    title: string;
+    formerTitles?: unknown;
+}
+/**
+ * Work out what `formerTitles` should be after a save.
+ *
+ * Returns `undefined` when there is nothing to record and nothing already held,
+ * so an ordinary save on a never-renamed page does not add an empty key to its
+ * frontmatter.
+ *
+ * @param existing - Current `formerTitles` value, straight off disk and untrusted
+ * @param previousTitle - The title the page had before this save
+ * @param newTitle - The title it is being given
+ * @returns The new list, or undefined when the field should stay absent
+ */
+export declare function computeFormerTitles(existing: unknown, previousTitle: string | undefined | null, newTitle: string | undefined | null): string[] | undefined;
+/**
+ * Derive a former-title → current-title lookup from the page set.
+ *
+ * Keys are lowercased, so resolution is case-insensitive in the same way the
+ * provider's title index is.
+ *
+ * A title held by a **live** page is marked ambiguous rather than resolving to
+ * whoever once held it: live resolution runs first and will have answered
+ * already, so reaching this map for a live title means something is wrong, and
+ * refusing is the safe reading.
+ *
+ * @param pages - Every page, with its title and raw `formerTitles` frontmatter
+ * @returns Map of lowercased former title → current title, or AMBIGUOUS
+ */
+export declare function buildFormerTitleIndex(pages: readonly FormerTitleSource[]): Map<string, string | typeof AMBIGUOUS>;

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

@@ -0,0 +1,54 @@
+/**
+ * frontmatterAccess — the single implementation of ACL Tier 1 (#1054).
+ *
+ * A page's frontmatter can restrict who may act on it, via `access[<action>]`
+ * or, for viewing, `audience`. Two subsystems needed that answer and each had
+ * its own version of it, which is how they came to disagree:
+ *
+ *   - `PolicyInformationPoint.checkFrontmatterAccess` decided a request, correctly.
+ *   - `VersioningFileProvider.getRecentChanges` decided a listing, and only
+ *     consulted `audience` for pages already marked private — so every
+ *     non-private page carrying an audience was listed to everyone, while
+ *     `/view/` on the same page returned 403.
+ *
+ * Both now call this. The invariant worth keeping is that anything which LISTS
+ * pages agrees with whatever DECIDES access, so a page can never appear in a
+ * listing its viewer cannot open.
+ *
+ * Pure and dependency-free so the provider layer can use it without reaching
+ * up into a manager.
+ */
+/** The frontmatter fields Tier 1 reads. */
+export interface AccessMetadataLike {
+    /** `{ view: ['role'], edit: [...] }` — per-action principal lists. */
+    access?: unknown;
+    /** Shorthand for `access.view`. */
+    audience?: unknown;
+}
+export interface FrontmatterDecision {
+    /** False when the page carries no rule for this action — caller falls through. */
+    decided: boolean;
+    /** Meaningful only when `decided`. */
+    allowed: boolean;
+    /** The principal that matched, for logging. */
+    matched?: string;
+}
+/**
+ * Principals permitted to perform `action`, or null when the page states no
+ * rule and the caller should fall through to global policy.
+ *
+ * `access[action]` wins; `audience` is the shorthand and applies to `view`
+ * only. An empty list counts as no rule — a page saying `audience: []`
+ * restricts nobody, which matters because a bare `access:` key parses that way.
+ */
+export declare function resolveFrontmatterPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
+/**
+ * Decide Tier 1 for a viewer described as a flat principal list — their roles
+ * plus their username. Callers holding a `UserContext` should pass
+ * `[...roles, username]`; the provider layer already works in these terms.
+ *
+ * Denies when the page states a rule and nothing matches. That default is the
+ * point: a listing that treats "no match" as "show it" is the bug this exists
+ * to prevent.
+ */
+export declare function decideFrontmatterAccess(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], action: string): FrontmatterDecision;

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

@@ -0,0 +1,55 @@
+/**
+ * Headless-install guard for the bootstrap admin password (#1087).
+ *
+ * `InstallService` documented a safety property the code did not have:
+ *
+ * > "There is no default — a headless install with that variable unset refuses
+ * > to start."
+ *
+ * It did not refuse. `ngdpbase.user.security.defaultpassword` ships as the
+ * literal `admin123`, and `UserManager.getBootstrapPassword()` falls back to a
+ * matching hardcoded constant when the key is missing or blank. So a headless
+ * container or k8s deploy with `NGDPBASE_ADMIN_PASSWORD` unset came up with
+ * `admin` / `admin123` — failing *open*, onto a credential published in this
+ * repository, where the documentation said it failed *closed*.
+ *
+ * This makes the documented behaviour real, for headless installs only.
+ *
+ * ## Why only headless
+ *
+ * A fresh local install coming up unattended so the setup wizard is reachable
+ * is a deliberate, documented property (`config/app-default-config.json`, the
+ * `_comment_user_security_defaultpassword` entry). There is a human present who
+ * will see the startup banner that `isAdminUsingDefaultPassword()` drives, and
+ * refusing to boot would strand them with no way in.
+ *
+ * An unattended deploy has neither the human nor the banner. That asymmetry is
+ * the whole reason this guard is scoped the way it is.
+ *
+ * ## Why it compares the value rather than reading the variable
+ *
+ * The check cannot simply ask whether `NGDPBASE_ADMIN_PASSWORD` is set, because
+ * the env-ref is opt-in: an operator supplies the password either by exporting
+ * that variable *and* pointing the config key at it, or by setting the key
+ * directly in `app-custom-config.json`. Both are legitimate. What actually
+ * matters is whether the resolved password is still the well-known shipped one,
+ * which catches both "variable unset" and "operator never changed the config".
+ *
+ * The cost is that an operator who deliberately chooses `admin123` is treated as
+ * having chosen nothing. That is the right trade.
+ */
+/** The bootstrap password shipped in `config/app-default-config.json`. */
+export declare const SHIPPED_BOOTSTRAP_PASSWORD = "admin123";
+/**
+ * Refuse a headless install that would create the admin account on the shipped
+ * password.
+ *
+ * Called only from the path that actually creates the account — an instance
+ * that already has an admin never reaches it, so an existing deployment is
+ * unaffected by a restart.
+ *
+ * @param resolvedPassword - The password `createDefaultAdmin` is about to use.
+ * @param isHeadless - Whether `HEADLESS_INSTALL=true`.
+ * @throws When headless and the password is absent or still the shipped one.
+ */
+export declare function assertHeadlessBootstrapPassword(resolvedPassword: string, isHeadless: boolean): void;

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

@@ -0,0 +1,52 @@
+/**
+ * imageTransform — shared image transform pipeline for Asset providers.
+ *
+ * Wraps sharp with a consistent options interface so all providers
+ * (BasicAttachmentProvider, FileSystemMediaProvider, future S3Provider, etc.)
+ * generate thumbnails and apply format conversions through a single code path.
+ *
+ * Part of Epic #405 Phase 6 — Transform pipeline.
+ */
+/**
+ * Options for a single image transform operation.
+ */
+export interface ImageTransformOptions {
+    /** Target width in pixels (omit to skip resizing) */
+    width?: number;
+    /** Target height in pixels (omit to skip resizing) */
+    height?: number;
+    /**
+     * Resize fit mode (default: 'inside').
+     *   inside   — preserve full image, letterbox to fit bounds
+     *   cover    — crop to fill bounds exactly
+     *   contain  — letterbox with background fill
+     *   fill     — stretch to exact bounds (may distort)
+     */
+    fit?: 'inside' | 'cover' | 'contain' | 'fill';
+    /** Output format (default: 'jpeg') */
+    format?: 'jpeg' | 'webp' | 'png';
+    /** Compression quality 1–100 (default: 85; ignored for png) */
+    quality?: number;
+}
+/**
+ * Transform an image using sharp.
+ *
+ * Accepts either a Buffer (e.g. a freshly uploaded file) or an absolute
+ * file path (e.g. a media-library file). Applies EXIF-based auto-rotation
+ * before resizing so orientation is always correct regardless of camera model.
+ *
+ * @param input   - Image buffer or absolute path to the source file
+ * @param options - Resize / format options
+ * @returns       - Transformed image as a Buffer
+ * @throws        - Re-throws sharp errors (caller should handle)
+ */
+export declare function transformImage(input: Buffer | string, options: ImageTransformOptions): Promise<Buffer>;
+/**
+ * Parse a size string of the form "WxH" (e.g. "300x300", "150x150").
+ *
+ * @returns `{ width, height }` on success, or `null` if the string is malformed.
+ */
+export declare function parseSize(size: string): {
+    width: number;
+    height: number;
+} | null;