@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,150 @@
+/**
+ * Where a page's footnotes and comments are kept, and through which I/O (#1839).
+ *
+ * A public page's are in the managers' own folders (`ngdpbase.footnotes.storagedir`,
+ * `ngdpbase.comments.storagedir`), as before. A vault page's — a page named
+ * `vaults/{owner}/{store}/{title}` — are inside that vault
+ * (`{store}/footnotes/{uuid}.json`, `{store}/comments/{uuid}/`), read and
+ * written through the vault's store I/O: sealed exactly when its pages are,
+ * refused when the vault is locked or is a sealed kind's vault that hasn't been
+ * opened. Nothing of a vault page is kept outside the vault (operator, 2026-10-16).
+ *
+ * The place is decided by the page's NAME, never by a uuid alone: a vault page
+ * is in no shared index, so its uuid says nothing about where it is. Who may
+ * read or write a page's notes is the caller's to decide (the page's own read
+ * and edit doors); nothing here decides access.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import { type StoreFileIO } from './privateStoreFiles.js';
+import { type PrivateStoreLayout } from './privateStorePath.js';
+export type PageNotesKind = 'footnotes' | 'comments';
+/** The page a footnote or comment belongs to: its name says where it is, its uuid which file. */
+export interface PageRef {
+    /** The page's name: a public title, or its vault name `vaults/{owner}/{store}/{title}`. */
+    name: string;
+    uuid: string;
+}
+/** Where one kind of note lives: the manager's public folder, and the vaults. */
+export interface PageNotesRoots {
+    kind: PageNotesKind;
+    /** The manager's own folder, for public pages. */
+    publicDir: string;
+    pagesDirectory: string;
+    layout: PrivateStoreLayout;
+}
+export interface PageNotesPath {
+    /** Footnotes: the page's `{uuid}.json`. Comments: the page's `{uuid}/` folder. */
+    path: string;
+    /** The vault the page is in; null for a public page. */
+    vault: {
+        owner: string;
+        store: string;
+    } | null;
+}
+interface EngineLike {
+    getManager<T = unknown>(name: string): T | undefined | null;
+}
+/**
+ * The roots for `kind`: the manager's own folder, and the vaults where the
+ * page provider keeps them (its `storagedir` and the configured layout), read
+ * when asked rather than kept.
+ */
+export declare function pageNotesRoots(engine: EngineLike, kind: PageNotesKind, publicDir: string): PageNotesRoots;
+/** Where `page`'s notes of this kind are on disk. Pure: no I/O, no key. */
+export declare function pageNotesPath(page: PageRef, roots: PageNotesRoots): PageNotesPath;
+/**
+ * Where `page`'s notes are and the I/O to use there, as `ctx` may. A vault
+ * that refuses `ctx` (locked, or a sealed kind's vault not yet opened) throws,
+ * for a read as for a write: a vault page's notes are never read or written
+ * in the clear.
+ */
+export declare function pageNotesPlace(ctx: ActorContext, page: PageRef, roots: PageNotesRoots): Promise<PageNotesPath & {
+    io: StoreFileIO;
+}>;
+/**
+ * Move a page's notes when the page changes place — into a vault, out of one,
+ * or between two — through both sides' I/O, as its history moves: sealed going
+ * into a sealed vault, opened coming out, never copied in the clear into a
+ * sealed one. A rename within one place moves nothing (the files are keyed by
+ * uuid). Both I/Os are resolved before anything moves.
+ *
+ * @returns true when something was moved
+ */
+export declare function movePageNotes(ctx: ActorContext, uuid: string, fromName: string, toName: string, roots: PageNotesRoots): Promise<boolean>;
+/**
+ * Move a vault page's notes left in the public folder before #1839 into its
+ * vault (the #1842 repair), through the vault's I/O: sealed when the vault is.
+ * Where the vault has none of this kind yet, this is the move
+ * {@link movePageNotes} makes. Where it already has some (written since
+ * #1839), the two are merged and the vault's own entries win; a comment file
+ * the vault already holds is never overwritten. The vault side is written
+ * before the public copy is removed, so a failure leaves two copies, never none.
+ *
+ * The vault's I/O is resolved first, so a locked vault, or a sealed kind's
+ * vault not yet opened, throws and nothing moves. Who may ask is the caller's
+ * to decide, and so is that `uuid` is a page of that vault.
+ *
+ * @param opts.dryRun - Count what would move, and move nothing
+ * @returns how many notes were (or would be) moved: footnotes, or comment files
+ */
+export declare function moveOutsideNotesIntoVault(ctx: ActorContext, vault: {
+    owner: string;
+    store: string;
+}, uuid: string, roots: PageNotesRoots, opts?: {
+    dryRun?: boolean;
+}): Promise<number>;
+/** A vault page whose notes of one kind are outside its vault (#1839). */
+export interface VaultPageNotesOutside {
+    owner: string;
+    vault: string;
+    /** The page, by uuid: a vault page's title is its owner's and is not logged. */
+    uuid: string;
+}
+/**
+ * Every vault page whose notes of `roots.kind` are in the manager's public
+ * folder rather than in its vault (#1839): written before notes moved into
+ * vaults, in the clear. A page is known by its file name (`{uuid}.md`), so the
+ * check needs no key and reads no page. Read only: nothing is moved, sealed or
+ * deleted; an administrator decides what to do with the files.
+ */
+export declare function findVaultPageNotesOutside(roots: PageNotesRoots): Promise<VaultPageNotesOutside[]>;
+/** Whether `uuid` is a page of `owner`'s vault `store`, live or in its trash: known by its file name, no key needed. */
+export declare function isVaultPageUuid(pagesDirectory: string, layout: PrivateStoreLayout, vault: {
+    owner: string;
+    store: string;
+}, uuid: string): Promise<boolean>;
+/** The manager state a startup check sets and clears: the manager's own (BaseManager). */
+export interface CheckStateHooks {
+    /** True when this is a new state. */
+    markDegraded(reason: string): boolean;
+    /** Clears the degraded state only while it is still `reason`, so another fault stays reported. */
+    markReadyIfDegradedBy(reason: string): boolean;
+}
+/**
+ * The check for {@link findVaultPageNotesOutside}, made the way the
+ * unsealed-vault check reports (#1834, #1836): an error in the log naming each
+ * owner, vault and page uuid, the manager's degraded state (the subsystem
+ * banner) and, at startup, a system notification. Nothing is moved or
+ * deleted. A failing check is logged, never thrown: it must not stop the
+ * manager starting.
+ *
+ * Run again after a repair (#1842), it keeps what it found for the repair
+ * actions to offer, and clears the degraded state it set once nothing is left.
+ */
+export declare class VaultPageNotesCheck {
+    private readonly engine;
+    private readonly roots;
+    private readonly state;
+    private found;
+    private reason;
+    constructor(engine: EngineLike, roots: () => PageNotesRoots, state: CheckStateHooks);
+    /** What the last run found. */
+    findings(): VaultPageNotesOutside[];
+    /**
+     * @param opts.notify - Send the system notification on a new state: at startup; a re-run after a repair does not
+     */
+    run(opts: {
+        notify: boolean;
+    }): Promise<VaultPageNotesOutside[]>;
+}
+export {};

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

@@ -0,0 +1,37 @@
+/**
+ * What a page title may contain (#1455).
+ *
+ * Declared once, applied at the `PageManager` save door, so every writer meets
+ * it: the editor, the NCM funnel (import, MCP, paste, convert, ingest), addons
+ * and scripts. It used to be written out three times in `WikiRoutes`, which is
+ * why the paths that do not go through a route — an import, an agent write —
+ * could put a title on disk that the editor would have refused.
+ *
+ * The characters are refused for three separate reasons, and each one is a
+ * defect somebody met:
+ *
+ *   - `/` breaks `/view/:page` routing, and `[store/Title]` — a private page's
+ *     link — can only be read if no title contains one (#1457).
+ *   - `\ # ? % " < > | *` break URLs, YAML frontmatter or file names.
+ *
+ * A private page's NAME is a path, `private/{owner}/{store}/{title}` (#1456).
+ * The rule is about the title, never the name.
+ */
+/** The characters a page title may not contain. */
+export declare const FORBIDDEN_TITLE_CHARS: RegExp;
+/** What a person is told when a title is refused — the editor's message. */
+export declare const TITLE_RULE_MESSAGE = "Page title contains invalid characters. The following are not allowed: / \\ # ? % \" < > | *";
+/** True when `title` breaks the rule. */
+export declare function titleBreaksRule(title: string): boolean;
+/**
+ * The same title with the forbidden characters replaced by `-`, for the NCM
+ * funnel, which converts someone else's data and must not drop a page over a
+ * character (operator, 2026-09-23: normalise and report). Runs of `-` collapse
+ * and the ends are trimmed, so `Docs/Setup` reads as `Docs-Setup` rather than
+ * `Docs--Setup-`.
+ *
+ * A caller that normalises says so in its report and records what the source
+ * called the page; the editor never normalises, because a person typing a
+ * title can simply be told.
+ */
+export declare function normaliseTitle(title: string): string;

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

@@ -0,0 +1,59 @@
+/**
+ * Slice 4 of #755 (#772) — page → schema.org `Article` mapper for the
+ * CatalogSource surface.
+ *
+ * This is the **internal CreativeWork** projection consumed by
+ * `CatalogManager.getCreativeWork('pages', uuid)` and the cross-source
+ * `list()` fan-out. It returns the typed `Article` from `src/types/Schema.ts`
+ * (no `@context`, no JSON-LD render quirks).
+ *
+ * Distinct from `src/utils/buildPageJsonLd.ts`, which builds the
+ * inline-`<script type="application/ld+json">` payload (Slice 6a / #765) and
+ * carries `@context` plus a few JSON-LD-render-only conventions. Per
+ * `docs/schemas.md` Decision 11: "AssetRecord (internal) + CreativeWork
+ * (JSON-LD render) coexist; render mapper converts." `pageToArticle` is the
+ * internal record; `buildPageJsonLd` is the render mapper. Both share the
+ * same source frontmatter and produce overlapping shapes — intentional, not
+ * duplicated logic.
+ *
+ * Ratified decisions honored (`docs/schemas.md`):
+ *   - Decision 4: `@id` = canonical URL `/view/<slug>`; UUID = `identifier`.
+ *   - Decision 5: `system-category` maps to `ngdp:category` (custom field,
+ *     `ngdp:` prefix policy).
+ *   - Decision 9: structured-data is JSON-LD only — this is the internal
+ *     record that the JSON-LD render step consumes.
+ *   - Decision 10: `author` immutable (original creator); `editor` mutable
+ *     (last-saver). Both surface here when present.
+ *   - Decision 13: `dateModified` = latest revision's timestamp (always
+ *     `lastModified`, never any older revision's timestamp).
+ *
+ * Required fields per `Article`:
+ *   - `@id`, `@type`, `identifier`, `name`, `url`.
+ * Optional fields are omitted (not emitted as `null`/empty) when source lacks
+ * them — JSON-LD consumers prefer absent over null.
+ */
+import type { Article } from '../types/Schema.js';
+import type { PageFrontmatter } from '../types/Page.js';
+export interface PageToArticleOptions {
+    /**
+     * Canonical base URL (e.g. `https://wiki.example.com`). When set, `@id` and
+     * `url` are absolute; otherwise they're path-only `/view/<slug>` (still a
+     * valid IRI per JSON-LD 1.1).
+     */
+    baseUrl?: string;
+    /**
+     * Auto-tagged keywords from the search index (#507 / TaggingService). Merged
+     * with frontmatter `user-keywords` + `system-keywords` and deduplicated.
+     */
+    autoTaggedKeywords?: string[];
+}
+/**
+ * Build the internal `Article` record for a single page.
+ *
+ * @param pageName    Page title — used as `name` and to compute `@id` / `url`.
+ *                    For slug-bearing pages, pass the slug from `metadata.slug`
+ *                    so the URL stays stable across renames.
+ * @param metadata    Frontmatter object (typically from `PageManager.getPageMetadata`).
+ * @param options     Optional `baseUrl` and `autoTaggedKeywords`.
+ */
+export declare function pageToArticle(pageName: string, metadata: PageFrontmatter | null | undefined, options?: PageToArticleOptions): Article;

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

@@ -0,0 +1,18 @@
+/**
+ * The URL of a page, and of an action on it (#1456, epic #1454).
+ *
+ * `/view/…` serves public pages only. A private page, named
+ * `vaults/{owner}/{store}/{title}`, lives at `/vaults/{owner}/{store}/{title}`,
+ * and every action on it lives under that path. This is the one place that
+ * turns a page name into a link, so routes, views and redirects agree.
+ * It holds no data and reads no config.
+ */
+/** The page actions that have a URL of their own. */
+export type PageAction = 'view' | 'edit' | 'save' | 'delete' | 'history' | 'diff';
+/**
+ * The URL for `action` on the page named `pageName`.
+ *
+ * @example pageUrl('Main') === '/view/Main'
+ * @example pageUrl('vaults/jim/default/Diary', 'edit') === '/vaults/jim/default/Diary/edit'
+ */
+export declare function pageUrl(pageName: string, action?: PageAction): string;

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

@@ -0,0 +1,12 @@
+export interface PasswordRecord {
+    password?: string;
+    sessionGeneration?: number;
+    /** ISO 8601; when the password last changed. Absent on an account that never changed it. */
+    passwordChangedAt?: string;
+}
+/** Change the record's password, in place. */
+export declare function setPassword(record: PasswordRecord, newPassword: string, now?: Date): Promise<void>;
+/** When the password last changed, in epoch seconds; null when it never has. */
+export declare function passwordChangedAtSeconds(record: {
+    passwordChangedAt?: unknown;
+} | null | undefined): number | null;

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

@@ -0,0 +1,60 @@
+/**
+ * Password hashing — scrypt, with a per-user salt and in-place upgrade (#1042).
+ *
+ * ## What was wrong
+ *
+ * Passwords were stored as ONE round of SHA-256 with a single instance-wide
+ * salt (`amdwiki-salt` by default):
+ *
+ *     sha256(password + globalSalt)
+ *
+ * SHA-256 is built to be fast, which is the opposite of what a password hash
+ * needs — an attacker holding `users.json` can try billions of candidates a
+ * second on commodity hardware. And because every account shared one salt,
+ * two users with the same password produced byte-identical hashes, so the
+ * store leaked which accounts shared a password without any cracking at all.
+ * The comparison was `===`, which is not constant-time.
+ *
+ * ## What replaces it
+ *
+ * scrypt from Node's standard library — no new dependency — with a random
+ * 16-byte salt per password and a constant-time comparison.
+ *
+ * The stored value is self-describing:
+ *
+ *     scrypt$131072$8$1$<salt base64>$<hash base64>
+ *
+ * Carrying the parameters in the hash is what makes this maintainable: the
+ * cost can be raised later and old hashes keep verifying under the parameters
+ * they were written with, then upgrade on next login. A bare digest cannot do
+ * that, which is how the SHA-256 scheme became impossible to move off.
+ *
+ * ## Migration
+ *
+ * Existing hashes cannot be converted — the plaintext is not recoverable. So
+ * legacy values keep verifying, `needsRehash()` reports them, and the caller
+ * rewrites them after a successful login. The store ages over as people sign
+ * in; nobody is locked out and no reset email is needed.
+ *
+ * An empty stored hash stays unusable by design: `isExternal` accounts (magic
+ * link, OIDC) store `''`, and no password may ever match it.
+ */
+/** Hash a password under the current scheme. */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify `password` against a stored value in EITHER scheme.
+ *
+ * @param stored      the value from the user record
+ * @param legacySalt  instance-wide salt, for pre-#1042 hashes only
+ */
+export declare function verifyPassword(password: string, stored: string, legacySalt: string): Promise<boolean>;
+/**
+ * Should this stored value be rewritten after a successful login?
+ *
+ * True for legacy hashes, and for current-scheme hashes written under weaker
+ * parameters than today's — which is how a future cost increase rolls out.
+ * An empty hash is never rehashed; external accounts have no password.
+ */
+export declare function needsRehash(stored: string): boolean;
+/** True when the value was written by the pre-#1042 scheme. */
+export declare function isLegacyHash(stored: string): boolean;

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

@@ -0,0 +1,52 @@
+/**
+ * Which permission entries are actions someone may hold (#1638 slice 3).
+ *
+ * Every audit event is declared on a permission entry, so the catalog also
+ * holds records that no one is ever permitted to do — `system-start`,
+ * `job-failed`, `authentication-failed`. Those entries carry
+ * `"grantable": false`. This is the one predicate that says so; everything
+ * that hands out, offers or lists permissions asks it: app (OIDC) scopes,
+ * the generated `CorePermission` type, the admin roles matrix and the
+ * permission listings. Omitted means grantable.
+ */
+/** True unless the entry says `"grantable": false`. */
+export declare function isGrantable(entry: unknown): boolean;
+/** The names of the grantable entries in a permission catalog, in catalog order. */
+export declare function grantablePermissionNames(definitions: unknown): string[];
+/** The grantable entries of a permission catalog, as a map in catalog order. */
+export declare function grantablePermissions<T>(definitions: Record<string, T> | null | undefined): Record<string, T>;
+/**
+ * Permissions that were split into narrower ones, and what each stood for.
+ *
+ * A policy, an agent token or an app grant written before the split still
+ * names the old permission; it is read as all of the new ones, so nobody loses
+ * an ability on upgrade. New writing should name the new permissions.
+ */
+export declare const RETIRED_PERMISSIONS: ReadonlyMap<string, readonly string[]>;
+/** The names with every retired permission replaced by what it stood for, de-duplicated, order kept. */
+export declare function withRetiredExpanded(names: readonly string[]): string[];
+/**
+ * What the standard OpenID Connect sign-in scopes let an app see, in plain
+ * words (#1572). They are not permissions, so they are not in the catalog;
+ * this is their one declaration — the consent page and the "My tokens and
+ * devices" list both read it through `describeScopes`.
+ */
+export declare const SIGN_IN_SCOPE_LABELS: Readonly<Record<string, string>>;
+/** One scope or permission as a person reads it: its name, and what it lets the holder do. */
+export interface ScopeDescription {
+    name: string;
+    description: string;
+}
+/**
+ * A permission entry in plain words (#1764): its `label` — the end-user line
+ * shown wherever a person reads what a permission does — else its
+ * `description` (an add-on that declares no label), else nothing.
+ */
+export declare function permissionLabel(entry: unknown): string | null;
+/**
+ * Scope or permission names in plain words (#1764), in order, without
+ * repeats: a sign-in scope by `SIGN_IN_SCOPE_LABELS`, a permission by
+ * `permissionLabel` of its catalog entry. A name declared nowhere (an app's
+ * own scope, such as a host's `patient/*.read`) is shown as itself.
+ */
+export declare function describeScopes(names: readonly string[], definitions: unknown): ScopeDescription[];