@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/utils/addonDatabaseRules.js

@@ -0,0 +1,57 @@
+/**
+ * The rules an add-on's database declaration follows (#1860), said once for
+ * every reader: the configuration merge, which refuses an add-on whose
+ * declaration breaks them, and DatabaseManager, which opens only a declared
+ * database.
+ *
+ * An add-on declares its database in its own `config/default-config.json`:
+ *
+ *     "ngdpbase.addons.<slug>.database": { "owner": "phr", "ledgerTable": "phr_schema_migrations", "encrypt": "required" }
+ *
+ * `owner` names the file (`<owner>.db`); an add-on that depends on the owner
+ * declares the owner's slug and a ledger of its own. `encrypt` is `"required"`
+ * (never opened without `NGDPBASE_DATABASE_KEY`) or `"optional"`.
+ */
+import { isPlainObject } from './configFiles.js';
+/** A canonical add-on slug: lowercase letters and digits, single dashes. */
+export const ADDON_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** The values `encrypt` may take. */
+export const DATABASE_ENCRYPT_VALUES = ['required', 'optional'];
+/** The fields a declaration has; any other field is refused, so a misspelt `encrypt` is not silently dropped. */
+const FIELDS = ['owner', 'ledgerTable', 'encrypt'];
+/** The configuration key under which an add-on declares its database. */
+export function addonDatabaseKey(slug) {
+    return `ngdpbase.addons.${slug}.database`;
+}
+/** The slug in a `ngdpbase.addons.<slug>.database` key, or null for any other key. */
+export function addonDatabaseKeySlug(key) {
+    return /^ngdpbase\.addons\.([^.]+)\.database$/.exec(key)?.[1] ?? null;
+}
+/** What a ledger table of this owner must start with: the slug, dashes as underscores, then `_`. */
+export function ledgerPrefix(owner) {
+    return `${owner.replace(/-/g, '_')}_`;
+}
+/** What is wrong with one declaration, one line per problem. Empty when sound. */
+export function addonDatabaseProblems(value) {
+    if (!isPlainObject(value))
+        return ['the declaration must be an object { owner, ledgerTable, encrypt }'];
+    const problems = [];
+    const { owner, ledgerTable, encrypt } = value;
+    if (typeof owner !== 'string' || !ADDON_SLUG.test(owner)) {
+        problems.push(`owner must be an add-on slug (lowercase letters and digits, single dashes), got ${JSON.stringify(owner)}`);
+    }
+    if (typeof ledgerTable !== 'string') {
+        problems.push(`ledgerTable must be a table name, got ${JSON.stringify(ledgerTable)}`);
+    }
+    else if (typeof owner === 'string' && ADDON_SLUG.test(owner) && !ledgerTable.startsWith(ledgerPrefix(owner))) {
+        problems.push(`ledgerTable '${ledgerTable}' must start with '${ledgerPrefix(owner)}'`);
+    }
+    if (!DATABASE_ENCRYPT_VALUES.includes(encrypt)) {
+        problems.push(`encrypt must be "required" or "optional", got ${JSON.stringify(encrypt)}`);
+    }
+    for (const field of Object.keys(value)) {
+        if (!FIELDS.includes(field))
+            problems.push(`'${field}' is not a field of a database declaration`);
+    }
+    return problems;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * What core hands an add-on: the third argument to `register` (#1813).
+ *
+ * An add-on used to reach core values by importing them from `../../dist/…`.
+ * That ties it to core's file layout and gives every add-on the same shared
+ * module objects. The host is instead built per add-on, from the running
+ * core's own values (imported here, never re-implemented), and frozen:
+ *
+ * - `logger` is a child tagged with the add-on's slug (`{ addon: slug }`);
+ * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
+ *   this add-on declares in its own `config/default-config.json`, so one
+ *   add-on cannot write records that look like another's or like core's;
+ * - the object is `Object.freeze`d, so no add-on can replace a value.
+ *
+ * Additive only: nothing here is removed or renamed without a major release.
+ * Anything an add-on needs that the host does not offer is added here by PR.
+ */
+import type { Logger } from 'winston';
+import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
+import { actorOf } from '../context/ActorContext.js';
+import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { guardedFetch } from '../http/guardedFetch.js';
+import { recordAuditEvent } from './auditEvents.js';
+import { addonAuditEventName } from './auditEventNames.js';
+/** The values core offers an add-on, under the names they were imported as. */
+export interface AddonHost {
+    readonly ApiContext: typeof ApiContext;
+    readonly ApiError: typeof ApiError;
+    readonly sendApiError: typeof sendApiError;
+    readonly recordAuditEvent: typeof recordAuditEvent;
+    readonly addonAuditEventName: typeof addonAuditEventName;
+    readonly actorOf: typeof actorOf;
+    readonly jobContextFromRequest: typeof jobContextFromRequest;
+    readonly jobContextFromSystem: typeof jobContextFromSystem;
+    readonly logger: Logger;
+    readonly guardedFetch: typeof guardedFetch;
+}
+/**
+ * The audit event names one add-on declares: the permission entries carrying
+ * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
+ * own `config/default-config.json` — read by the one declarations reader.
+ */
+export declare function addonDeclaredAuditEvents(addonDefaults: Record<string, unknown>): ReadonlySet<string>;
+/**
+ * Build the frozen host for one add-on.
+ *
+ * @param slug - The add-on's canonical slug
+ * @param addonDefaults - That add-on's own default-config.json, as folded into
+ *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ */
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;

package/lib/src/utils/addonHost.js

@@ -0,0 +1,72 @@
+/**
+ * What core hands an add-on: the third argument to `register` (#1813).
+ *
+ * An add-on used to reach core values by importing them from `../../dist/…`.
+ * That ties it to core's file layout and gives every add-on the same shared
+ * module objects. The host is instead built per add-on, from the running
+ * core's own values (imported here, never re-implemented), and frozen:
+ *
+ * - `logger` is a child tagged with the add-on's slug (`{ addon: slug }`);
+ * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
+ *   this add-on declares in its own `config/default-config.json`, so one
+ *   add-on cannot write records that look like another's or like core's;
+ * - the object is `Object.freeze`d, so no add-on can replace a value.
+ *
+ * Additive only: nothing here is removed or renamed without a major release.
+ * Anything an add-on needs that the host does not offer is added here by PR.
+ */
+import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
+import { actorOf } from '../context/ActorContext.js';
+import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { guardedFetch } from '../http/guardedFetch.js';
+import { recordAuditEvent } from './auditEvents.js';
+import { addonAuditEventName } from './auditEventNames.js';
+import { auditDeclarationsFrom } from './auditRegistry.js';
+import logger from './logger.js';
+/**
+ * The audit event names one add-on declares: the permission entries carrying
+ * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
+ * own `config/default-config.json` — read by the one declarations reader.
+ */
+export function addonDeclaredAuditEvents(addonDefaults) {
+    return new Set(Object.keys(auditDeclarationsFrom((key, fallback) => addonDefaults[key] ?? fallback)));
+}
+function refuseUndeclared(slug, name, declared) {
+    if (declared.has(name))
+        return;
+    const message = `Add-on '${slug}' may record only the audit events it declares in its config/default-config.json; ` +
+        `'${name}' is not one of them (declared: ${declared.size > 0 ? [...declared].sort().join(', ') : 'none'}).`;
+    logger.error(`[addons] ${message}`);
+    throw new Error(message);
+}
+/**
+ * Build the frozen host for one add-on.
+ *
+ * @param slug - The add-on's canonical slug
+ * @param addonDefaults - That add-on's own default-config.json, as folded into
+ *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ */
+export function buildAddonHost(slug, addonDefaults) {
+    const declared = addonDeclaredAuditEvents(addonDefaults);
+    const hostAddonAuditEventName = (name) => {
+        const checked = addonAuditEventName(name);
+        refuseUndeclared(slug, name, declared);
+        return checked;
+    };
+    const hostRecordAuditEvent = async (sink, event, onError) => {
+        refuseUndeclared(slug, event.eventType, declared);
+        return recordAuditEvent(sink, event, onError);
+    };
+    return Object.freeze({
+        ApiContext,
+        ApiError,
+        sendApiError,
+        recordAuditEvent: hostRecordAuditEvent,
+        addonAuditEventName: hostAddonAuditEventName,
+        actorOf,
+        jobContextFromRequest,
+        jobContextFromSystem,
+        logger: logger.child({ addon: slug }),
+        guardedFetch
+    });
+}

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

@@ -0,0 +1,109 @@
+/**
+ * The add-on installer (#1830): install the npm add-ons a site's configuration
+ * names into `<data>/addons/<slug>/`, pinned and verified.
+ *
+ * AddonsManager owns it and calls {@link installConfiguredAddons} at boot,
+ * before discovery. This module holds the mechanics only — registry, integrity,
+ * provenance, unpacking, the lock file — and takes its outbound HTTP, its
+ * provenance check and its audit hook as parameters, so the only network it
+ * reaches is the guarded client AddonsManager hands it (src/http, #1139).
+ *
+ * As decided on #1810:
+ * - An add-on already in the lock file is used from disk, after its stored
+ *   tarball's sha512 is checked against the lock and the unpacked folder
+ *   against that tarball. No registry call. A folder that differs from its
+ *   tarball is rewritten from it; a tarball that fails its sha512 is not
+ *   trusted, so the folder is set aside and the add-on is not loaded.
+ * - An add-on not yet installed is resolved from the registry packument: the
+ *   highest release in the configured range whose `ngdpbase.minVersion` this
+ *   core meets (#1757). Its tarball's sha512 must equal the packument's
+ *   `dist.integrity`; its Sigstore provenance must be valid for that tarball
+ *   and name the configured repository; and its own package.json must name the
+ *   same package, version and slug (the registry metadata and the tarball are
+ *   not trusted to agree — "manifest confusion").
+ * - Registry unreachable, or anything refused: that add-on is skipped with a
+ *   reason, and the boot continues. It is tried again at the next start.
+ */
+import { type ProvenanceResult } from './addonProvenance.js';
+/** One configured add-on: `ngdpbase.addons.install.<slug>`. */
+export interface InstallSpec {
+    package: string;
+    version: string;
+    /** The source repository its provenance must name, e.g. `github.com/jwilleke/yourphr`. */
+    repository: string;
+}
+/** The outbound GET the installer is given. Throws when the host cannot be reached. */
+export type RegistryFetch = (url: string, options: {
+    maxBytes: number;
+    accept: string;
+}) => Promise<{
+    status: number;
+    body: Buffer;
+}>;
+/** Check a release's attestations. Throws when the check cannot be made (trust root unreachable). */
+export type ProvenanceCheck = (input: {
+    attestations: unknown;
+    name: string;
+    version: string;
+    sha512Hex: string;
+    repository: string;
+}) => Promise<ProvenanceResult>;
+/** What is about to be installed, for the audit record written before it is. */
+export interface InstallRecord {
+    slug: string;
+    package: string;
+    version: string;
+    integrity: string;
+    repository: string;
+    /** The version this replaces, when the configuration moved it. */
+    previousVersion?: string;
+}
+export interface InstallerOptions {
+    /** `<data>/addons`: each add-on unpacks into a folder here. */
+    addonsDir: string;
+    /** Registry base URL, e.g. https://registry.npmjs.org */
+    registry: string;
+    /** This core's version, for `ngdpbase.minVersion`. */
+    coreVersion: string;
+    maxPackumentBytes: number;
+    maxTarballBytes: number;
+    maxUnpackedBytes: number;
+    fetch: RegistryFetch;
+    checkProvenance: ProvenanceCheck;
+    /**
+     * Called once everything is verified and before anything is written. If it
+     * throws (an audit record that must be written could not be), nothing is
+     * installed.
+     */
+    beforeInstall?: (record: InstallRecord) => Promise<void>;
+    now?: () => Date;
+}
+export type InstallStatus = 
+/** Installed now from the registry. */
+'installed'
+/** Already installed; verified against the lock, nothing changed. */
+ | 'verified'
+/** Already installed; the folder differed from its verified tarball and was rewritten. */
+ | 'repaired'
+/** Not installed (and not loaded); `reason` says why. */
+ | 'skipped';
+/** Which verification refused, for `addon-verify-failed`. */
+export type FailedCheck = 'integrity' | 'provenance' | 'tarball' | 'manifest' | 'lock' | 'folder';
+export interface InstallOutcome {
+    slug: string;
+    status: InstallStatus;
+    package?: string;
+    version?: string;
+    reason?: string;
+    /** Registry (or the provenance trust root) could not be reached — the case admins are told to wait out. */
+    registryUnreachable?: boolean;
+    /** Set when a verification refused, or (for `repaired`) found the folder changed. */
+    failedCheck?: FailedCheck;
+}
+/** `sha512-<base64>` of `data`. */
+export declare function sha512Integrity(data: Buffer): string;
+/**
+ * Install or verify every add-on in `specs` (`ngdpbase.addons.install`).
+ * Never throws for one add-on's problem: each outcome says what happened.
+ */
+export declare function installConfiguredAddons(specs: Record<string, unknown>, opts: InstallerOptions): Promise<InstallOutcome[]>;

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

@@ -0,0 +1,37 @@
+/**
+ * The installed add-ons' lock file, `<data>/addons/addons-lock.json` (#1830).
+ *
+ * The installer (`addonInstaller.ts`) is its only writer. It is read here as
+ * well, synchronously and with no other dependency, because the configuration
+ * merge (`addonConfigLayer.ts`) runs before any manager and has to know which
+ * folders in `<data>/addons` are installed add-ons at all: a folder the lock
+ * does not name is never an add-on, whatever it contains.
+ */
+/** What the lock records for one installed add-on. */
+export interface LockEntry {
+    package: string;
+    version: string;
+    integrity: string;
+    installedAt: string;
+    /** The verified Sigstore provenance the install was accepted on. */
+    provenance: {
+        repository: string;
+        verifiedAt: string;
+    };
+}
+export interface LockFile {
+    lockfileVersion: 1;
+    addons: Record<string, LockEntry>;
+}
+export declare const LOCK_FILE_NAME = "addons-lock.json";
+/** Verified tarballs, kept so a restart needs no registry. Dot-named: discovery skips it. */
+export declare const PACKAGES_DIR_NAME = ".packages";
+export declare function lockFilePath(addonsDir: string): string;
+/** The lock file, or an empty one when there is none. Throws when it exists and is not JSON. */
+export declare function readLockSync(addonsDir: string): LockFile;
+/**
+ * The folders in `addonsDir` that are installed add-ons for this site: named
+ * in the lock file AND in the configured install map, and present on disk.
+ * An unreadable lock file names none.
+ */
+export declare function lockedAddonDirsSync(addonsDir: string, configuredSlugs: Iterable<string>): string[];

package/lib/src/utils/addonLock.js

@@ -0,0 +1,48 @@
+/**
+ * The installed add-ons' lock file, `<data>/addons/addons-lock.json` (#1830).
+ *
+ * The installer (`addonInstaller.ts`) is its only writer. It is read here as
+ * well, synchronously and with no other dependency, because the configuration
+ * merge (`addonConfigLayer.ts`) runs before any manager and has to know which
+ * folders in `<data>/addons` are installed add-ons at all: a folder the lock
+ * does not name is never an add-on, whatever it contains.
+ */
+import fs from 'fs';
+import path from 'path';
+export const LOCK_FILE_NAME = 'addons-lock.json';
+/** Verified tarballs, kept so a restart needs no registry. Dot-named: discovery skips it. */
+export const PACKAGES_DIR_NAME = '.packages';
+export function lockFilePath(addonsDir) {
+    return path.join(addonsDir, LOCK_FILE_NAME);
+}
+/** The lock file, or an empty one when there is none. Throws when it exists and is not JSON. */
+export function readLockSync(addonsDir) {
+    const file = lockFilePath(addonsDir);
+    if (!fs.existsSync(file))
+        return { lockfileVersion: 1, addons: {} };
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { lockfileVersion: 1, addons: parsed.addons ?? {} };
+}
+/**
+ * The folders in `addonsDir` that are installed add-ons for this site: named
+ * in the lock file AND in the configured install map, and present on disk.
+ * An unreadable lock file names none.
+ */
+export function lockedAddonDirsSync(addonsDir, configuredSlugs) {
+    let lock;
+    try {
+        lock = readLockSync(addonsDir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const slug of configuredSlugs) {
+        if (!lock.addons[slug])
+            continue;
+        const dir = path.join(addonsDir, slug);
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            out.push(dir);
+    }
+    return out;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Stable content hash of an addon page body. Trimmed so a trailing-newline
+ * difference between the source file and the on-disk form does not read as a
+ * modification. This is the value stamped into a seeded page's
+ * `addon-source-hash` frontmatter.
+ */
+export declare function pageSourceHash(content: string): string;
+/**
+ * Frontmatter key a required page's live copy carries: `pageSourceHash` of the
+ * body it was seeded or synced with (#1395). The required-pages analogue of
+ * `addon-source-hash`, read by the same `evaluateSeededAddonPage()`.
+ */
+export declare const REQUIRED_SOURCE_HASH_KEY = "required-source-hash";
+/** Reseed status of an addon page that ALREADY exists in the instance. */
+export type SeededAddonPageStatus = 'current' | 'outdated' | 'locally-modified';
+/**
+ * Decide what should happen to an already-seeded addon page, given its source
+ * body, its current live body, and the `addon-source-hash` stamped at seed time.
+ *
+ *  - `current`          — live body already matches source; nothing to do.
+ *  - `outdated`         — source changed and the live page is unmodified since
+ *                         seed (stored hash matches live), OR the page is legacy
+ *                         (no stored hash — pre-#920 seed; treated as reseedable
+ *                         since the previous body is kept as a revertable version).
+ *                         Safe to reseed.
+ *  - `locally-modified` — source changed but the live body differs from what was
+ *                         last seeded (⇒ operator-edited). Skip; never clobber.
+ */
+export declare function evaluateSeededAddonPage(args: {
+    sourceContent: string;
+    liveContent: string;
+    storedHash: string | undefined;
+}): SeededAddonPageStatus;
+/**
+ * Default edit access for a page ngdpbase ships (#971, #1411): a `general`
+ * page is instance-owned and gets no stamp; any other category — system,
+ * documentation, addon, unclassified — is administrator-edit only. A source
+ * that declares its own `access` overrides this.
+ *
+ * @param category - The page's resolved `system-category`
+ * @returns The access object to stamp, or undefined to leave the page unprotected
+ */
+export declare function defaultShippedPageAccess(category: unknown): {
+    edit: string[];
+} | undefined;

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

@@ -0,0 +1,48 @@
+/**
+ * Sigstore provenance of an npm add-on (#1830, decided on #1810): before an
+ * add-on is installed, its SLSA provenance attestation must be valid for the
+ * exact tarball and name the repository the site expects it to be built from.
+ *
+ * The registry serves a package's attestations at `dist.attestations.url`.
+ * The SLSA one is a Sigstore bundle: a DSSE envelope around an in-toto
+ * statement, signed with a short-lived Fulcio certificate issued to the CI
+ * workflow that built it, and logged in Rekor. Verification here:
+ *
+ * - the bundle verifies against the Sigstore trusted root (Fulcio chain,
+ *   transparency log, timestamps), with `@sigstore/verify`;
+ * - the certificate's identity is a workflow of the expected repository
+ *   (subject alternative name under `https://<repository>/`) and its issuer is
+ *   that host's CI (GitHub Actions or GitLab CI);
+ * - the statement's subject is this package and version, and its sha512 is
+ *   the tarball's.
+ *
+ * The trusted root is passed in: `sigstoreTrustedRoot.ts` fetches it through
+ * the guarded client. Nothing here opens the network.
+ */
+export type ProvenanceResult = {
+    ok: true;
+    repository: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `github.com/owner/repo` from any of `github.com/owner/repo`,
+ * `https://github.com/owner/repo`, `git+https://github.com/owner/repo.git`.
+ * Null when it is not host/owner/repo.
+ */
+export declare function normaliseRepository(value: string): string | null;
+/** The package URL npm puts in the statement's subject. */
+export declare function npmPurl(name: string, version: string): string;
+/**
+ * Check the attestations the registry returned for `name@version` against the
+ * tarball's sha512 (hex) and the expected repository.
+ */
+export declare function verifyProvenance(input: {
+    attestations: unknown;
+    name: string;
+    version: string;
+    sha512Hex: string;
+    repository: string;
+    trustedRoot: unknown;
+}): ProvenanceResult;

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

@@ -0,0 +1,41 @@
+/**
+ * Reading and unpacking an add-on's npm tarball safely (#1830), with `tar`.
+ *
+ * Every entry is checked in a reading pass before a byte reaches the disk:
+ *
+ * - only regular files and directories; a link (symbolic or hard), device or
+ *   FIFO refuses the whole tarball, so nothing can point outside the add-on's
+ *   folder;
+ * - a path that is absolute, holds `..`, a backslash or NUL, or is empty once
+ *   npm's leading `package/` folder is removed, refuses the whole tarball;
+ * - the unpacked size is counted as the entries are read and the read is
+ *   aborted at the cap, so a tarball that inflates enormously stops there;
+ * - tar runs `strict`, so a malformed header is an error, not a warning.
+ *
+ * Unpacking then runs `tar.x` into a fresh staging folder (with the same type
+ * filter, `strip: 1`, no preserved paths, no preserved owners), which is
+ * renamed into place only when it is complete.
+ *
+ * Refusing the whole tarball, not skipping the bad entry, is deliberate: a
+ * package that carries one is not the package its author published, and
+ * installing the rest of it would be a guess.
+ */
+/** A file in the package, by its path without npm's leading `package/`. */
+export type TarballFiles = Map<string, Buffer>;
+/**
+ * The path as it will be written, relative to the add-on folder: npm's leading
+ * folder (normally `package/`) removed, and refused if it could reach outside.
+ */
+export declare function safeEntryPath(raw: string): string;
+/**
+ * Read and check every entry of the gzipped tarball. Resolves to its files;
+ * rejects on the first thing that is not safe or not understood.
+ */
+export declare function readTarball(tgz: Buffer, maxUnpackedBytes: number): Promise<TarballFiles>;
+/**
+ * Unpack the (already checked) tarball at `tgzPath` into `target`: into a
+ * fresh staging folder beside it, then swapped in.
+ */
+export declare function unpackTarball(tgzPath: string, target: string): Promise<void>;
+/** Whether `dir` holds exactly `files`, byte for byte, and nothing else (no links). */
+export declare function folderMatches(dir: string, files: TarballFiles): Promise<boolean>;

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

@@ -0,0 +1,76 @@
+/**
+ * Shared parsing/discovery for the `ngdpbase.managers.addons-manager.addons-path`
+ * config value.
+ *
+ * #924: `AddonsManager` (real runtime discovery) and `ConfigurationManager`
+ * (the #672 boot-time "does this enabled addon exist" safety check) used to
+ * each carry their own copy of this logic. They drifted: `AddonsManager` was
+ * updated for #673's `node_modules:<glob>` packaged-addon syntax, but the
+ * validator's copy was not, so it resolved a `node_modules:` entry as a
+ * literal (non-existent) directory and treated every packaged addon as
+ * "unknown" — crashing boot the moment one was enabled. Consolidating the
+ * parsing/matching into one module removes the class of bug, not just this
+ * instance of it.
+ */
+/** Prefix marking an addons-path entry as an npm-package glob rather than a directory. */
+export declare const NPM_ADDON_PREFIX = "node_modules:";
+export interface SplitAddonsPath {
+    /** Plain directory entries (bundled/drop-in), not yet resolved to absolute. */
+    directories: string[];
+    /** npm package name globs (the part after `node_modules:`), e.g. `@jwilleke/*-addon`. */
+    npmPatterns: string[];
+}
+/**
+ * Coerce the raw config value (string or string[]) and split it into
+ * filesystem directory entries vs. `node_modules:<glob>` npm patterns.
+ */
+export declare function splitAddonsPath(raw: unknown): SplitAddonsPath;
+/** The config key naming the add-ons to install (#1830). */
+export declare const ADDONS_INSTALL_KEY = "ngdpbase.addons.install";
+/**
+ * Where installed add-ons live (#1830): `<data>/addons`, one folder per slug.
+ * Only a folder the lock file names, for a slug still in the install map, is
+ * an add-on (see `addonLock.ts`); anything else there is never loaded.
+ */
+export declare function installedAddonsDir(dataFolder: string, cwd?: string): string;
+/** The slugs `ngdpbase.addons.install` names, from a merged or shipped+custom view. */
+export declare function configuredInstallSlugs(config: Record<string, unknown>): string[];
+/** Locate the `node_modules` directory to search for packaged addons (resolved from cwd). */
+export declare function findNodeModulesDir(cwd?: string): string | null;
+/**
+ * Expand a `@scope/glob` (or bare `glob`) npm pattern to matching package
+ * directories under `nmRoot`.
+ */
+export declare function matchNpmPackageDirs(nmRoot: string, pattern: string): string[];
+/**
+ * Best-effort addon identity for a packaged (npm) addon directory, derived
+ * from its package-directory name alone — no module import, matching the
+ * same boot-time-speed, no-module-loading design already accepted for the
+ * directory-scan case (see `ConfigurationManager.assertConfiguredAddonsExist`).
+ *
+ * Follows the documented packaged-addon naming convention
+ * (`@scope/<slug>-addon`, see docs/platform/deployment/addon-packaged.md):
+ * strips a trailing `-addon` suffix if present, else returns the folder name
+ * as-is.
+ *
+ * Caveat (same class as the existing directory-name heuristic): the addon's
+ * *real* identity is whatever its module exports as `name` at runtime. A
+ * package that doesn't follow the `-addon` naming convention, or whose
+ * module exports a different `name`, won't be matched precisely here — this
+ * is a validation-time approximation, not the source of truth.
+ */
+export declare function deriveAddonSlugFromPackageDirName(dirName: string): string;
+/**
+ * Canonical identity for an addon directory (#927), resolved the SAME
+ * import-free way in every layer (discovery, `isEnabled`, the boot-time
+ * validator) so the four historical identities (folder name, module `name`,
+ * config key, manifest slug) can no longer drift:
+ *
+ *   canonicalId = package.json `ngdpbase.slug`  ??  deriveAddonSlugFromPackageDirName(folder)
+ *
+ * Reads `package.json` statically — never imports the module — which is what
+ * lets the boot validator compute the exact id the runtime will register
+ * under, instead of guessing. The module's exported `name` is a display
+ * label validated against this at load time, not a source of identity.
+ */
+export declare function resolveAddonSlug(addonDir: string, source: 'directory' | 'npm'): string;