@jwilleke/ngdpbase-types 5.26.0 → 5.28.0

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

@@ -1,5 +1,5 @@
 import BaseManager from '../managers/BaseManager.js';
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import { WikiEngine } from '../types/WikiEngine.js';
 import type { AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
 import type { Request } from 'express';
@@ -46,6 +46,12 @@ interface UserContext {
     viaProxy?: ProxyClaim;
     [key: string]: unknown;
 }
+/**
+ * What the page questions take (#2022): the caller's context as given — a
+ * request's subject or a job's `JobContext` — or a subject already in decision
+ * form. They convert it themselves, through {@link asSubject}.
+ */
+type PageQuestionCaller = ActorContext | UserContext | null | undefined;
 /**
  * Access decision log entry
  */
@@ -173,6 +179,15 @@ declare class PolicyInformationPoint extends BaseManager {
      * visitor holds, which is the safe answer for someone who no longer exists.
      */
     resolveSubjectNow(username: string | undefined): Promise<UserContext>;
+    /**
+     * The subject as a page's own rules match it (#2022): for a job's subject
+     * (`resolveRolesNow`, #1212), its username with the roles its account
+     * holds NOW, read through {@link resolveSubjectNow} — the path the PDP
+     * takes for the same subject; anyone else as carried. A job carries no
+     * roles, so matching it without this matched none, and an audience naming
+     * a role its user holds left the job out.
+     */
+    private matchableNow;
     /**
      * Who is making this request: the subject the session middleware resolved,
      * else the session's account resolved now, else the anonymous visitor.
@@ -209,6 +224,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 +347,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
@@ -340,14 +363,14 @@ declare class PolicyInformationPoint extends BaseManager {
      * private page gets at Tier 0: the owner, or a delegate of the owner; never
      * a role. A refusal is recorded like any page refusal (`authorization-deny`).
      *
-     * @param userContext - the request's subject, as given (null = anonymous)
+     * @param caller - the caller's context, as given: a request's subject or a job's (#2022); null is anonymous
      * @param owner - the container's owner (a private file's `creator`)
      * @param resource - what is being reached, for the record (e.g. `attachment:<id>`)
      * @param action - the action asked for (e.g. `view`)
      * @param vault - the vault inside the container, when the question is about one:
      *   a share link the owner issued gets in only for a vault it names (#1388)
      */
-    canAccessPrivateContainer(userContext: UserContext | null | undefined, owner: string, resource: string, action: string, vault?: string): boolean;
+    canAccessPrivateContainer(caller: PageQuestionCaller, owner: string, resource: string, action: string, vault?: string): boolean;
     /**
      * Check whether a user can access a given page — for cross-page checks where
      * the current WikiContext describes a DIFFERENT page than the one being
@@ -373,14 +396,14 @@ declare class PolicyInformationPoint extends BaseManager {
      *     case.
      *   - any tier returns deny.
      *
-     * @param userContext - The user requesting access (may be null / anonymous).
+     * @param caller      - The caller's context, as given: a request's subject or a job's (#2022); null / undefined is anonymous.
      * @param pageName    - Target page to check.
      * @param action      - Action verb (e.g., `'view'`, `'edit'`, `'delete'`).
      * @param knownMetadata - The page's metadata when the caller has just
      *   resolved it: the page door (#1622), which reads the page by the same
      *   resolution it decides on. Omitted, it is loaded here.
      */
-    canUserAccessPage(userContext: UserContext | null | undefined, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
+    canUserAccessPage(caller: PageQuestionCaller, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
     /**
      * {@link canUserAccessPage} as an affordance (#1668): would the door allow
      * this action on that page — asked only to decide whether to show a control
@@ -391,7 +414,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * @param knownMetadata - As for {@link canUserAccessPage}: the page's
      *   metadata when the caller has just resolved it (`PageManager.mayShowPage`).
      */
-    pageAffordanceFor(userContext: UserContext | null | undefined, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
+    pageAffordanceFor(caller: PageQuestionCaller, pageName: string, action: string, knownMetadata?: PageFrontmatter): Promise<boolean>;
     /** The cross-page check, for the door (`record`) or an affordance (#1668). */
     private crossPageDecision;
     /**
@@ -417,7 +440,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * A candidate without metadata is not listed (#714's convention). Order is
      * preserved. Returns titles.
      */
-    filterAccessiblePages(userContext: UserContext | null | undefined, action: string, candidates: ReadonlyArray<{
+    filterAccessiblePages(caller: PageQuestionCaller, action: string, candidates: ReadonlyArray<{
         title: string;
         metadata: PageFrontmatter | null | undefined;
     }>): Promise<string[]>;
@@ -437,12 +460,27 @@ declare class PolicyInformationPoint extends BaseManager {
      * A refusal is audited as `authorization-deny` on the media resource, with
      * the share attribution when there is one.
      */
-    canUserAccessMediaItem(userContext: UserContext | null | undefined, item: MediaItem): Promise<boolean>;
+    canUserAccessMediaItem(caller: PageQuestionCaller, 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 caller - the caller's context, as given (a job's included, #2022)
+     * @param metadata - the page's current frontmatter
+     */
+    audienceAdmits(caller: PageQuestionCaller, 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/User.d.ts

@@ -73,7 +73,7 @@ export interface User {
     /**
      * @deprecated since #617 iteration 3b. Role membership is now stored
      * canonically as OrganizationRole records owned by `RoleManager`; resolve
-     * a user's roles via `RoleManager.resolveUserRoles(username)`. The field
+     * a user's roles via `RoleManager.resolveUserRoles(ctx, username)`. The field
      * is retained as optional for backwards compatibility while in-flight
      * `users.json` files still carry it; the `strip-user-roles.ts` migration
      * removes it. New code MUST NOT read or write this field directly.

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

@@ -15,6 +15,8 @@
  *   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
@@ -36,6 +38,8 @@ import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/gu
 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;
@@ -76,7 +80,21 @@ export interface AddonHost {
     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>;
 /**
@@ -94,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,8 @@
  *   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
@@ -64,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);
@@ -90,6 +111,8 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         logger: logger.child({ addon: slug }),
         guardedFetch,
         setEnabledForPerson,
+        registerShim: (shim) => iceRegistry('shim', shim?.name).registerShim(slug, shim),
+        registerReceiver: (receiver) => iceRegistry('receiver', receiver?.name).registerReceiver(slug, receiver),
         resolveEgressPolicy,
         validateUrl,
         createGuardedElasticsearchClient,

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

@@ -50,9 +50,9 @@ 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 */
+    /** A user 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 */
+    /** A user'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";
@@ -112,21 +112,21 @@ export declare const AUDIT_EVENT: {
     readonly POLICY_EVALUATE: "policy-evaluate";
     /** Security posture at startup, compared against the previous start */
     readonly POSTURE_RECORDED: "posture-recorded";
-    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    /** Proxy grant made: someone may act for the user named in user; actor is who made it (#1762) */
     readonly PROXY_GRANT: "proxy-grant";
-    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    /** Proxy grant ended: revoked, or the account closed; user is the user represented, actor who ended it (#1762) */
     readonly PROXY_REVOKE: "proxy-revoke";
-    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the person represented, actor the person signed in (#1762) */
+    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the user represented, actor the user signed in (#1762) */
     readonly PROXY_SWITCH: "proxy-switch";
-    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    /** Step-up: a re-authentication failed (wrong password, another user's passkey, throttled) */
     readonly REAUTH_FAILURE: "reauth-failure";
     /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
     readonly REAUTH_PROMPT: "reauth-prompt";
-    /** Step-up: the person re-authenticated, with the factor used */
+    /** Step-up: the user re-authenticated, with the factor used */
     readonly REAUTH_SUCCESS: "reauth-success";
     /** Page search; not recorded, read volume */
     readonly SEARCH_PAGE: "search-page";
-    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */
     readonly SEARCH_USER: "search-user";
     /** A masked configuration value shown to an administrator; the key is recorded, never the value */
     readonly SECRET_REVEAL: "secret-reveal";
@@ -146,9 +146,9 @@ export declare const AUDIT_EVENT: {
     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) */
+    /** Sign-in approval: the user pressed Approve (#1532) */
     readonly SIGNINAPPROVAL_APPROVE: "signinapproval-approve";
-    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    /** Sign-in approval: the user 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";

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

@@ -57,9 +57,9 @@ 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 */
+    /** A user 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 */
+    /** A user'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',
@@ -119,21 +119,21 @@ export const AUDIT_EVENT = {
     POLICY_EVALUATE: 'policy-evaluate',
     /** Security posture at startup, compared against the previous start */
     POSTURE_RECORDED: 'posture-recorded',
-    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    /** Proxy grant made: someone may act for the user named in user; actor is who made it (#1762) */
     PROXY_GRANT: 'proxy-grant',
-    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    /** Proxy grant ended: revoked, or the account closed; user is the user represented, actor who ended it (#1762) */
     PROXY_REVOKE: 'proxy-revoke',
-    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the person represented, actor the person signed in (#1762) */
+    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the user represented, actor the user signed in (#1762) */
     PROXY_SWITCH: 'proxy-switch',
-    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    /** Step-up: a re-authentication failed (wrong password, another user's passkey, throttled) */
     REAUTH_FAILURE: 'reauth-failure',
     /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
     REAUTH_PROMPT: 'reauth-prompt',
-    /** Step-up: the person re-authenticated, with the factor used */
+    /** Step-up: the user re-authenticated, with the factor used */
     REAUTH_SUCCESS: 'reauth-success',
     /** Page search; not recorded, read volume */
     SEARCH_PAGE: 'search-page',
-    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */
     SEARCH_USER: 'search-user',
     /** A masked configuration value shown to an administrator; the key is recorded, never the value */
     SECRET_REVEAL: 'secret-reveal',
@@ -153,9 +153,9 @@ export const AUDIT_EVENT = {
     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) */
+    /** Sign-in approval: the user pressed Approve (#1532) */
     SIGNINAPPROVAL_APPROVE: 'signinapproval-approve',
-    /** Sign-in approval: the person pressed Deny; that sign-in will not complete (#1532) */
+    /** Sign-in approval: the user 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',

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

@@ -12,6 +12,12 @@
  * A route turns it into the answer with `ApiContext.enforceDeny(err.permission,
  * err.decision)`, the one place a refusal is shaped (#1431); the door never
  * builds an HTTP answer itself.
+ *
+ * Every lookup takes a context too (#2018, operator 2026-10-23), through
+ * {@link requireRecordAccess}: a user's own identity record under
+ * `profile-manage`, anyone else's under `contact-read` / `contact-manage`, and
+ * core's own reads under the system context without a policy evaluation, so
+ * resolving roles on every request stays cheap.
  */
 import { type ActorContext } from '../context/ActorContext.js';
 import type { CorePermission } from '../security/permissions.generated.js';
@@ -37,6 +43,30 @@ export declare class ContactRefusedError extends Error {
  * refuses: closed, never open.
  */
 export declare function requireContactPermission(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, also?: readonly CorePermission[]): Promise<void>;
+/**
+ * Core's own work (#2018): a boot or schedule context naming the system
+ * principal, with no token, share or proxy claim. Recognised by its fields
+ * alone, with no policy evaluation, because RoleManager resolves roles
+ * through these lookups on every request. A request never carries this
+ * context: the system principal's name is reserved, so no account holds it.
+ */
+export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | null | undefined): boolean;
+/**
+ * A lookup or change of one record at a contacts door (#2018). Throws
+ * {@link ContactRefusedError} unless `ctx` may:
+ *
+ * - read it as core's own work ({@link isSystemWork}): allowed, not evaluated;
+ * - read or change its own identity record (the context's username is the
+ *   record's `identifier`): `profile-manage`, which every user holds;
+ * - read or change any other record: `contact-read` / `contact-manage`.
+ *
+ * `record` is the identity record (or what names it, `{ identifier }`); left
+ * out for a record that is never anyone's own (an organization, a role).
+ * "Own" is decided by comparing usernames, never by a role.
+ */
+export declare function requireRecordAccess(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, record?: {
+    identifier?: unknown;
+} | null): Promise<void>;
 /** What a contacts record says was done. Names fields, never their values. */
 export interface ContactChange {
     kind: 'person' | 'organization';

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

@@ -2,8 +2,8 @@
  * 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:
+ * or `audience`, which covers every action (#1964). 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
@@ -22,7 +22,7 @@
 export interface AccessMetadataLike {
     /** `{ view: ['role'], edit: [...] }` — per-action principal lists. */
     access?: unknown;
-    /** Shorthand for `access.view`. */
+    /** Who may act on the page at all; administrators excepted (#1964). */
     audience?: unknown;
 }
 export interface FrontmatterDecision {
@@ -34,21 +34,64 @@ export interface FrontmatterDecision {
     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.
+ * The page's `audience`, or null when it names none (#1964, operator
+ * 2026-10-23). An audience restricts EVERY action: someone outside it may
+ * neither read nor edit the page.
+ */
+export declare function audiencePrincipals(metadata: AccessMetadataLike | null | undefined): string[] | null;
+/**
+ * The page's `access[action]` list, or null when it states none. It applies
+ * to that action only, and to everyone — administrators included.
+ */
+export declare function accessPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
+/**
+ * The entry `addon:<slug>` (#1964): "people who turned on the per-person
+ * add-on <slug>". It is matched only against the viewer's enabled add-ons,
+ * never against a role or a username.
+ */
+export declare const ADDON_PRINCIPAL_PREFIX = "addon:";
+/**
+ * Whether deciding `action` on this page needs the viewer's enabled add-ons —
+ * so a caller asks for them only when the page names one (#1964).
  */
-export declare function resolveFrontmatterPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
+export declare function namesAddonPrincipal(metadata: AccessMetadataLike | null | undefined, action: string): boolean;
+/**
+ * Every add-on slug the page names in `audience` or in any `access` list, once
+ * each, in the order first named — for the warning about a slug that can match
+ * nobody (#1964).
+ */
+export declare function addonAudienceSlugs(metadata: AccessMetadataLike | null | undefined): string[];
+/**
+ * Whether the page's audience leaves this viewer out — true only when it
+ * names one and nothing in it matches. The caller then asks whether the
+ * viewer is an administrator, the one exception (#1964), and passes the
+ * answer to {@link decideFrontmatterAccess}; it asks only when this is true.
+ */
+export declare function audienceExcludes(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], enabledAddons?: readonly string[]): boolean;
+/** The `matched` an administrator outside the audience is admitted by. */
+export declare const AUDIENCE_ADMIN_MATCH = "admin-system";
 /**
  * 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.
  *
+ * Two rules, in order (#1964, operator 2026-10-23):
+ *
+ * - __`audience`__ applies to every action. Someone it leaves out may neither
+ *   read nor edit the page: every action is refused. The one exception is an
+ *   administrator — a viewer holding `admin-system`, which the caller decides
+ *   and passes as `isAdmin` (this module never reads a role for it). For
+ *   `view`, a viewer the audience admits is allowed; for any other action it
+ *   only lets them through to `access` and then policy.
+ * - __`access[action]`__ applies to that action, to everyone, administrators
+ *   included. When the page states it, it decides.
+ *
+ * An `addon:<slug>` entry matches only when `<slug>` is in `enabledAddons`,
+ * the viewer's enabled per-person add-ons (#1964); a caller that does not
+ * supply them matches no such entry, so it can under-list but never leak.
+ *
  * 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;
+export declare function decideFrontmatterAccess(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], action: string, enabledAddons?: readonly string[], isAdmin?: boolean): FrontmatterDecision;

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

@@ -0,0 +1,64 @@
+/**
+ * Per-run summary persistence for NCM / import conversion outcomes (#738).
+ *
+ * Writes one JSON file per import run under FAST_STORAGE (configurable via
+ * `ngdpbase.import.runs-dir`, default `./data/import-runs`). Each file's
+ * name is the ISO timestamp of `startedAt`, sanitised for filesystem use.
+ *
+ * The trend view (admin-import.ejs) reads the last N summaries via
+ * listRecentRuns() to surface dominant failure causes across runs.
+ *
+ * Append-only by design. Retention is operator-managed for now — the
+ * directory can grow indefinitely; a future cleanup job (or admin button)
+ * can prune. Listed as a follow-up in the #738 acceptance criteria.
+ */
+/** Compact per-run record persisted to disk. */
+export interface ImportRunSummary {
+    /** Stable id; same as the filename without `.json`. */
+    runId: string;
+    /** ISO-8601 timestamp of when the run started. */
+    startedAt: string;
+    /** ISO-8601 timestamp of when the run finished (may equal startedAt for trivial runs). */
+    finishedAt: string;
+    /** What kind of import surfaced this run (`paste`, `url`, `file`, `ingest:<sourceId>`). */
+    importType: string;
+    /**
+     * Who initiated the run — `ImportOptions.actorContext.username` (#1236): the
+     * request's subject for a manual import, the system principal for a job.
+     */
+    actor: string;
+    /**
+     * True when the run was a job with no person behind it (a JobContext whose
+     * origin is boot, schedule or operator) — lets the trend view distinguish
+     * "alice triggered an import" from "scheduled feed ingested overnight".
+     * False for a request, or a request-origin job.
+     */
+    isSystem?: boolean;
+    /** Where the run came from: `request`, `boot`, `schedule` or `operator` (#1236). Absent on records written before it. */
+    origin?: string;
+    /** Total items the run attempted. */
+    total: number;
+    /** Items successfully converted to pages. */
+    converted: number;
+    /** Items intentionally skipped (e.g. duplicates). */
+    skipped: number;
+    /** Items that failed to convert. */
+    failed: number;
+    /**
+     * Counts of ConversionWarning.kind values aggregated across all items in the run.
+     * Keys are flat (no colon-subkinds today) per the #738 design decision.
+     */
+    kindCounts: Record<string, number>;
+}
+/** Aggregate a flat list of ConversionWarning-like objects into kindCounts. */
+export declare function tallyWarnings(warnings: Array<{
+    kind: string;
+}> | undefined): Record<string, number>;
+/** Write a single per-run summary. Idempotent for same runId. Best-effort — errors logged, never thrown. */
+export declare function writeRunSummary(runsDir: string, summary: ImportRunSummary): Promise<void>;
+/**
+ * Return the most-recent N run summaries, newest first. Filenames are ISO
+ * timestamps so lexicographic sort is chronological. Missing/empty dir
+ * returns []. Malformed individual files are skipped, not fatal.
+ */
+export declare function listRecentRuns(runsDir: string, limit?: number): Promise<ImportRunSummary[]>;

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

@@ -0,0 +1,31 @@
+/**
+ * KeyedSerial — one task at a time per key, within this process (#2015).
+ *
+ * A read-modify-write of one record (read the file, change it, write it back)
+ * is only safe while nothing else writes that record in between. Two role
+ * changes to one role used to interleave: each read the member list before the
+ * other wrote it, and the second write dropped the first one's member. Running
+ * every read-modify-write of a key through `run` makes them happen one after
+ * another, each reading what the last one wrote. Different keys still run side
+ * by side.
+ *
+ * What it does not do:
+ *
+ * - **Not across processes.** Two server processes sharing one data folder can
+ *   still race; no supported deployment runs that way.
+ * - **Not re-entrant.** A task must not `run` the same key again and wait for
+ *   it: the inner task queues behind the outer one, which never finishes.
+ *
+ * A failed task fails its own caller only; the next task on the key runs as
+ * usual. A key's entry is dropped once its queue is empty, so the map holds
+ * only keys with work in flight.
+ */
+export declare class KeyedSerial {
+    /** The settled tail of each key's queue: never rejects. */
+    private readonly tails;
+    /** Run `task` after every earlier task on `key` has settled; resolves or rejects as `task` does. */
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+    /** Resolves once every task queued so far, on every key, has settled (shutdown). */
+    settled(): Promise<void>;
+}
+export default KeyedSerial;

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

@@ -0,0 +1,30 @@
+/**
+ * NCM conversion → /admin/notifications (#728 Phase 2 Slice 5d)
+ *
+ * Operator decision 2026-05-17: on **non-preview** NCM conversion paths
+ * (bulk import, #685 ingestion, MCP) — where no human sees the preview — a
+ * summary of the conversion warnings is pushed to the existing
+ * `/admin/notifications` centre via `NotificationManager` (the same
+ * subsystem `MediaManager` already feeds), so admins get an actionable
+ * per-event alert. Distinct from #738 (aggregate metrics/trend).
+ *
+ * Engine-coupled glue lives here (not in `src/converters/ncm/`, which is
+ * kept pure). Best-effort and non-blocking — notification failure must never
+ * fail a conversion.
+ *
+ * @module utils/ncmNotify
+ */
+interface EngineLike {
+    getManager(name: string): unknown;
+}
+/**
+ * Push an admin notification summarising NCM conversion warnings.
+ * No-op when there are no warnings or NotificationManager is unavailable.
+ *
+ * @param engine   Wiki engine (structural — just needs getManager)
+ * @param source   Human label for the path, e.g. "Import jspwiki", "MCP create_page"
+ * @param target   The page/file that was converted
+ * @param warnings Flattened `"kind: detail"` strings
+ */
+export declare function notifyNcmConversion(engine: EngineLike, source: string, target: string, warnings: string[]): void;
+export {};