@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -146,6 +146,20 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * cannot be asked by accident. The subject is the PIP's, resolved live.
      */
     userHoldsPermission(username: string, action: string): Promise<boolean>;
+    /**
+     * The usernames of every account that holds a permission, each asked through
+     * {@link userHoldsPermission} (#1813; was `utils/administrators.ts`). With
+     * `admin-system` this is "who are the administrators": the people an
+     * operator problem is reported to (#1431 7b, #1916), never a role name.
+     *
+     * An empty answer means "nobody to tell", and a caller sending a
+     * notification must then only log it: an empty `targetUsers` list means
+     * every user in NotificationManager.
+     *
+     * @returns The usernames, or null when there is no UserManager to list
+     *   accounts from (tests, a half-booted engine); treat that like nobody
+     */
+    usersHolding(action: string): Promise<string[] | null>;
     /**
      * The permissions a user's roles give them, for display (#1431 step 10).
      *

package/lib/src/security/PolicyInformationPoint.d.ts

@@ -209,6 +209,12 @@ declare class PolicyInformationPoint extends BaseManager {
      * none when it is not running.
      */
     subjectEnabledAddons(ctx: ActorContext): Promise<string[]>;
+    /**
+     * {@link subjectEnabledAddons} for a page decision (#1964): none for no
+     * subject, and none when the lookup fails — an `addon:<slug>` entry then
+     * matches nobody, never everyone.
+     */
+    private enabledAddonsOf;
     private userManager;
     private roleManager;
     /**
@@ -326,7 +332,9 @@ declare class PolicyInformationPoint extends BaseManager {
      * - __Tier 0.5, author-lock__, `edit` only. It only denies: an author, or a
      *   subject holding `admin-system` (#1431 7b), falls through to Tier 1+.
      * - __Tier 1, frontmatter__ `access[action]` / `audience`. Page-level, and
-     *   overrides global policy when it states a rule (#1054).
+     *   overrides global policy when it states a rule (#1054). An `audience`
+     *   covers every action, and a subject holding `admin-system` is its one
+     *   exception; `access` has none (#1964).
      * - __Tier 2.__ For a share visitor the share IS the policy (#1222); for
      *   anyone else, global policy.
      * - __Default deny.__ Nothing below Tier 2 grants — JSPWiki's page-body ACL
@@ -439,10 +447,25 @@ declare class PolicyInformationPoint extends BaseManager {
      */
     canUserAccessMediaItem(userContext: UserContext | null | undefined, item: MediaItem): Promise<boolean>;
     /**
-     * Check front matter audience / access fields (Tier 1.5).
+     * Check front matter audience / access fields (Tier 1).
      * Returns a decision object; decided=false means no front matter restriction — fall through.
+     *
+     * An audience that leaves the subject out refuses every action, unless the
+     * subject holds `admin-system` (#1964, operator 2026-10-23): asked only
+     * then. `access[action]` has no such exception.
      */
     private checkFrontmatterAccess;
+    /**
+     * Does the page's `audience` admit this subject (#1964)? True when the page
+     * names no audience, the subject matches it, or the subject holds
+     * `admin-system`. The same rule Tier 1 applies, asked by PageManager's
+     * write door, so a write cannot reach a page its writer is outside the
+     * audience of — whatever route it came by. Records nothing; the door does.
+     *
+     * @param userContext - the subject, as given
+     * @param metadata - the page's current frontmatter
+     */
+    audienceAdmits(userContext: UserContext | null | undefined, metadata: PageFrontmatter | null | undefined): Promise<boolean>;
     /**
      * Record/audit an access decision.
      * Accepts either a single object or positional args for backward compatibility.

package/lib/src/types/Config.d.ts

@@ -121,6 +121,8 @@ export interface WikiConfig {
      * counting every failure inside it (#1916). Default: 60.
      */
     'ngdpbase.mail.failure-notice.window-minutes': number;
+    /** The most a message's attachments may total, in bytes (#1974). Default: 10485760. */
+    'ngdpbase.mail.attachments.max-bytes': number;
     /**
      * Anti-spam: max submissions per IP per `window-minutes` window before
      * the 429 trips (#670 Phase E). Default: 5.

package/lib/src/types/Consent.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Consent to a site's documents (#1603): the shapes ConsentManager and its
+ * callers share, and what an add-on registers.
+ */
+/** Whose document it is: core's (`core`) or an add-on's slug. */
+export type ConsentScope = string;
+/** Where a person is asked to accept (#1603): `?scope=` (core when absent) and `?returnTo=`. */
+export declare const CONSENT_PATH = "/consent";
+/** The scope of core's own documents, `ngdpbase.consent.documents`. */
+export declare const CORE_CONSENT_SCOPE = "core";
+/**
+ * A document a person is asked to accept, as it stands now: a page whose
+ * front matter carries `version:` and `effective:`. Read from the page each
+ * time, never copied.
+ */
+export interface ConsentDocument {
+    /** The page's slug, which is also the document's id in a record (`terms-of-service`, `phr-privacy-policy`). */
+    id: string;
+    scope: ConsentScope;
+    /** The page's title, to show. */
+    title: string;
+    /** The page's `version:`, as a string. A change asks everyone again. */
+    version: string;
+    /** The page's `effective:` date (`YYYY-MM-DD`), or null when it names none. */
+    effective: string | null;
+}
+/** What a person saw when they accepted: each document and the version shown. */
+export interface ConsentSeen {
+    id: string;
+    version: string;
+}
+/**
+ * One acceptance, one line of the person's file. Append-only: a later
+ * version is a later line, nothing is rewritten.
+ */
+export interface ConsentRecord {
+    kind: 'accept';
+    document: string;
+    scope: ConsentScope;
+    version: string;
+    effective: string | null;
+    /** ISO 8601 time the person accepted. */
+    acceptedAt: string;
+    /**
+     * The account this was accepted on, by its creation time (#1937): a later
+     * account that takes the same username never inherits it.
+     */
+    account?: string;
+    /** Who and how: the account, where from, and the way they were asked (`sign-up`, `sign-in`, `add-on`). */
+    context: {
+        by: string;
+        how: string;
+        origin: string;
+        ipAddress?: string;
+    };
+}
+/** One document's state for a person, for "Your consents" on /profile. */
+export interface ConsentStatus {
+    document: ConsentDocument;
+    /** Their acceptance of the current version, or null: not accepted (never, or only an older version). */
+    current: ConsentRecord | null;
+    /** Their latest acceptance of any version, or null. */
+    latest: ConsentRecord | null;
+}
+/** What an add-on registers at load (#1603). */
+export interface AddonConsentRegistration {
+    /**
+     * Page slugs of the add-on's documents, each starting `<slug>-`
+     * (`phr-terms-of-service`, `phr-privacy-policy`). Shipped as the add-on's
+     * own pages, with `version:` and `effective:` front matter.
+     */
+    documents: string[];
+    /**
+     * URL path prefixes where a person uses the add-on in the browser
+     * (`/phr`). A person who has it on and has not accepted a changed version
+     * is asked there before going on. Optional: without it they are asked
+     * only when they next turn it on.
+     */
+    paths?: string[];
+}
+/**
+ * Thrown when a per-person add-on is turned on before its documents are
+ * accepted (#1603). `documents` names what is still to accept.
+ */
+export declare class ConsentRequiredError extends Error {
+    readonly scope: ConsentScope;
+    readonly documents: string[];
+    readonly name = "ConsentRequiredError";
+    constructor(scope: ConsentScope, documents: string[]);
+}

package/lib/src/types/express.d.ts

@@ -45,6 +45,12 @@ declare module 'express-session' {
         pendingRedirect?: string;
         /** A verified outside identity no account has connected, waiting for the person to sign in another way (#1743). */
         pendingConnection?: PendingConnection;
+        /**
+         * Set at sign-in when the person has core terms to accept at their current
+         * version (#1603); the consent gate holds the session to the prompt until
+         * they accept (or sign out). Cleared by the acceptance.
+         */
+        consentPending?: boolean;
         /** When this session last made a request, epoch ms — kept only while an idle timeout is set (#1546). */
         lastActivity?: number;
         /** When this session signed in, epoch ms: the start of `ngdpbase.session.max-age` (#1767). A re-authentication never moves it. */

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

@@ -15,6 +15,12 @@
  *   the add-on (#1973);
  * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
  *   bound to its slug, so it can never set another add-on's;
+ * - `registerShim` and `registerReceiver` (#1979, ICE) register into the import
+ *   engine under this add-on's slug, and only the names its manifest declares;
+ * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
+ *   are core's own pure functions, handed on unchanged, so an add-on never
+ *   imports them from `dist/` (#1813);
  * - 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.
@@ -26,8 +32,14 @@ import { actorOf, type ActorContext } from '../context/ActorContext.js';
 import { jobContextFromRequest, jobContextFromSystem, type JobContext } from '../context/JobContext.js';
 import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
+import { resolveEgressPolicy } from '../http/egressPolicy.js';
+import { validateUrl } from '../http/ssrf.js';
+import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
+import { isAtLeast } from './version.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
+import type { IceReceiver, IceShim } from '../ice/types.js';
+import type { AddonManifest } from '../managers/AddonsManager.js';
 /** The values core offers an add-on, under the names they were imported as. */
 export interface AddonHost {
     readonly ApiContext: typeof ApiContext;
@@ -54,7 +66,35 @@ export interface AddonHost {
      * does not say `perPerson: true`, or the person may not manage their profile.
      */
     readonly setEnabledForPerson: PersonSwitchSetter;
+    /**
+     * The site's egress policy, read through `read` (a `ConfigurationManager.getProperty`
+     * reader) each time it is called, so an operator tightening it applies at once.
+     * Hand its `policy` to `guardedFetch` or `validateUrl`.
+     */
+    readonly resolveEgressPolicy: typeof resolveEgressPolicy;
+    /** Whether a URL may be fetched under an egress policy, before any socket: http(s) and an allowed literal address. */
+    readonly validateUrl: typeof validateUrl;
+    /** An Elasticsearch client whose every connection is judged by the egress policy; the only way to build one. */
+    readonly createGuardedElasticsearchClient: typeof createGuardedElasticsearchClient;
+    /** The one boot-time line for an Elasticsearch node the egress policy refuses. */
+    readonly refusedNodeMessage: typeof refusedNodeMessage;
+    /** Whether an `x.y.z` version is at least another; throws on a version that is not `x.y.z`. */
+    readonly isAtLeast: typeof isAtLeast;
+    /**
+     * #1979 (ICE, D6): register an import shim, as `<slug>.<shim.name>`. Call it
+     * in `register`. Refused when the manifest's `shims` does not name it.
+     * Returns the shim's id; site configuration switches it on and off.
+     */
+    readonly registerShim: (shim: IceShim) => string;
+    /**
+     * #1979 (ICE, D4): register a receiver — your manager's own door for what
+     * shims produce — as `<slug>.<receiver.name>`. Refused when the manifest's
+     * `receivers` does not name it. Returns the receiver's id.
+     */
+    readonly registerReceiver: (receiver: IceReceiver) => string;
 }
+/** What the host may register for an add-on: the shim and receiver names its manifest declares (#1979). */
+export type AddonIceDeclaration = Pick<AddonManifest, 'shims' | 'receivers'>;
 /** Sets one add-on's per-person switch; core binds the slug when it builds the host (#1963). */
 export type PersonSwitchSetter = (ctx: ActorContext, on: boolean) => Promise<void>;
 /**
@@ -72,6 +112,9 @@ export declare function addonDeclaredAuditEvents(addonDefaults: Record<string, u
  * @param setEnabledForPerson - This add-on's switch setter, slug already bound
  *   (`AddonsManager` supplies it); without one, the host's setter refuses
  * @param engine - The running engine, which names the system principal for
- *   `systemContext`; without one (a test) it is core's fallback principal
+ *   `systemContext` and holds the import engine `registerShim` reaches;
+ *   without one (a test) it is core's fallback principal, and no registry
+ * @param manifest - The add-on's manifest (`ngdpbase` in its package.json):
+ *   the shims and receivers it may register (#1979)
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof systemContext>[0]): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof systemContext>[0], manifest?: AddonIceDeclaration | null): AddonHost;

package/lib/src/utils/addonHost.js

@@ -15,6 +15,12 @@
  *   the add-on (#1973);
  * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
  *   bound to its slug, so it can never set another add-on's;
+ * - `registerShim` and `registerReceiver` (#1979, ICE) register into the import
+ *   engine under this add-on's slug, and only the names its manifest declares;
+ * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
+ *   are core's own pure functions, handed on unchanged, so an add-on never
+ *   imports them from `dist/` (#1813);
  * - 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.
@@ -25,6 +31,10 @@ import { actorOf } from '../context/ActorContext.js';
 import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
 import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
+import { resolveEgressPolicy } from '../http/egressPolicy.js';
+import { validateUrl } from '../http/ssrf.js';
+import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
+import { isAtLeast } from './version.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import { auditDeclarationsFrom } from './auditRegistry.js';
@@ -56,10 +66,29 @@ function refuseUndeclared(slug, name, declared) {
  * @param setEnabledForPerson - This add-on's switch setter, slug already bound
  *   (`AddonsManager` supplies it); without one, the host's setter refuses
  * @param engine - The running engine, which names the system principal for
- *   `systemContext`; without one (a test) it is core's fallback principal
+ *   `systemContext` and holds the import engine `registerShim` reaches;
+ *   without one (a test) it is core's fallback principal, and no registry
+ * @param manifest - The add-on's manifest (`ngdpbase` in its package.json):
+ *   the shims and receivers it may register (#1979)
  */
-export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPersonSwitch, engine) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPersonSwitch, engine, manifest) {
     const declared = addonDeclaredAuditEvents(addonDefaults);
+    const names = (list) => new Set(Array.isArray(list) ? list.filter((n) => typeof n === 'string') : []);
+    const iceDeclared = { shim: names(manifest?.shims), receiver: names(manifest?.receivers) };
+    const iceRegistry = (what, name) => {
+        const allowed = iceDeclared[what];
+        if (typeof name !== 'string' || !allowed.has(name)) {
+            const message = `Add-on '${slug}' may register only the ${what}s its manifest declares ("ngdpbase": { "${what}s": [...] } in package.json); ` +
+                `'${String(name)}' is not one of them (declared: ${allowed.size > 0 ? [...allowed].sort().join(', ') : 'none'}).`;
+            logger.error(`[addons] ${message}`);
+            throw new Error(message);
+        }
+        const registry = engine?.getManager('ImportManager');
+        if (typeof registry?.registerShim !== 'function' || typeof registry.registerReceiver !== 'function') {
+            throw new Error(`register${what === 'shim' ? 'Shim' : 'Receiver'} is not available: this host was built without a site's ImportManager`);
+        }
+        return registry;
+    };
     const hostAddonAuditEventName = (name) => {
         const checked = addonAuditEventName(name);
         refuseUndeclared(slug, name, declared);
@@ -81,6 +110,13 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         systemContext: (reason) => systemContext(engine, reason),
         logger: logger.child({ addon: slug }),
         guardedFetch,
-        setEnabledForPerson
+        setEnabledForPerson,
+        registerShim: (shim) => iceRegistry('shim', shim?.name).registerShim(slug, shim),
+        registerReceiver: (receiver) => iceRegistry('receiver', receiver?.name).registerReceiver(slug, receiver),
+        resolveEgressPolicy,
+        validateUrl,
+        createGuardedElasticsearchClient,
+        refusedNodeMessage,
+        isAtLeast
     });
 }

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -50,6 +50,10 @@ export declare const AUDIT_EVENT: {
     readonly CONFIG_CHANGE: "config-change";
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     readonly CONFIG_RESET: "config-reset";
+    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    readonly CONSENT_GRANT: "consent-grant";
+    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    readonly CONSENT_WITHDRAW: "consent-withdraw";
     /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
     readonly CONTACT_MANAGE: "contact-manage";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
@@ -140,6 +144,22 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_EXTEND: "share-extend";
     /** Share link revoked; pairs with token-revoke */
     readonly SHARE_REVOKE: "share-revoke";
+    /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
+    readonly SIGNINAPPROVAL_ABANDON: "signinapproval-abandon";
+    /** Sign-in approval: the person pressed Approve (#1532) */
+    readonly SIGNINAPPROVAL_APPROVE: "signinapproval-approve";
+    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    readonly SIGNINAPPROVAL_DENY: "signinapproval-deny";
+    /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
+    readonly SIGNINAPPROVAL_EXPIRE: "signinapproval-expire";
+    /** Sign-in approval: the approval page was opened, with the opener's IP and browser; opening changes nothing (#1532) */
+    readonly SIGNINAPPROVAL_OPEN: "signinapproval-open";
+    /** Sign-in approval: an approval message was sent for a waiting sign-in, saying from where (IP, approximate place, browser) (#1532) */
+    readonly SIGNINAPPROVAL_REQUEST: "signinapproval-request";
+    /** Sign-in approval: the approval message could not be sent (transport error, or no channel configured) (#1532) */
+    readonly SIGNINAPPROVAL_SENDFAIL: "signinapproval-sendfail";
+    /** Sign-in approval: another approval message was asked for too soon and not sent (#1532) */
+    readonly SIGNINAPPROVAL_THROTTLE: "signinapproval-throttle";
     /** A user's private store copy created at its door (#1414) — with key material when sealed; never the words or a key in the record */
     readonly STORE_CREATE: "store-create";
     /** A takeout imported into its owner's private store; a bulk write — who, which store, pages and files written or skipped */

package/lib/src/utils/auditEventNames.generated.js

@@ -57,6 +57,10 @@ export const AUDIT_EVENT = {
     CONFIG_CHANGE: 'config-change',
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     CONFIG_RESET: 'config-reset',
+    /** A person accepted a document they are asked to accept (#1603): which document (core's terms-of-service or privacy-policy, or an add-on's), its version and effective date, and how (sign-up, sign-in, turning an add-on on). Recorded before the acceptance is stored, which cannot proceed without it: consent must be provable */
+    CONSENT_GRANT: 'consent-grant',
+    /** A person's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
+    CONSENT_WITHDRAW: 'consent-withdraw',
     /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
     CONTACT_MANAGE: 'contact-manage',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
@@ -147,6 +151,22 @@ export const AUDIT_EVENT = {
     SHARE_EXTEND: 'share-extend',
     /** Share link revoked; pairs with token-revoke */
     SHARE_REVOKE: 'share-revoke',
+    /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
+    SIGNINAPPROVAL_ABANDON: 'signinapproval-abandon',
+    /** Sign-in approval: the person pressed Approve (#1532) */
+    SIGNINAPPROVAL_APPROVE: 'signinapproval-approve',
+    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    SIGNINAPPROVAL_DENY: 'signinapproval-deny',
+    /** Sign-in approval: a waiting sign-in expired before it was completed (#1532) */
+    SIGNINAPPROVAL_EXPIRE: 'signinapproval-expire',
+    /** Sign-in approval: the approval page was opened, with the opener's IP and browser; opening changes nothing (#1532) */
+    SIGNINAPPROVAL_OPEN: 'signinapproval-open',
+    /** Sign-in approval: an approval message was sent for a waiting sign-in, saying from where (IP, approximate place, browser) (#1532) */
+    SIGNINAPPROVAL_REQUEST: 'signinapproval-request',
+    /** Sign-in approval: the approval message could not be sent (transport error, or no channel configured) (#1532) */
+    SIGNINAPPROVAL_SENDFAIL: 'signinapproval-sendfail',
+    /** Sign-in approval: another approval message was asked for too soon and not sent (#1532) */
+    SIGNINAPPROVAL_THROTTLE: 'signinapproval-throttle',
     /** A user's private store copy created at its door (#1414) — with key material when sealed; never the words or a key in the record */
     STORE_CREATE: 'store-create',
     /** A takeout imported into its owner's private store; a bulk write — who, which store, pages and files written or skipped */