@jwilleke/ngdpbase-types 5.27.0 → 5.29.0

package/lib/src/managers/RoleManager.d.ts

@@ -12,6 +12,9 @@ declare class RoleManager extends BaseManager {
     private storageDir;
     private memberCache;
     private byOrgPositionCache;
+    private cacheGeneration;
+    /** #2015: one membership change at a time per role record, read included. */
+    private readonly membership;
     private metricsRef;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
@@ -42,7 +45,8 @@ declare class RoleManager extends BaseManager {
     backupFolders(): BackupFolder[];
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
-    getById(id: string): Promise<Role | null>;
+    /** One role record by `@id`: its members are identity records, so `contact-read`, or core's own work (#2018). */
+    getById(ctx: ActorContext, id: string): Promise<Role | null>;
     getByOrgAndPosition(organizationId: string, namedPosition: string): Promise<Role | null>;
     listByMember(personId: string): Promise<Role[]>;
     list(): Promise<Role[]>;
@@ -63,10 +67,16 @@ declare class RoleManager extends BaseManager {
      * The pseudo-roles `'Authenticated'` and `'All'` are NOT added here — the
      * caller adds those when constructing `userContext.roles`.
      *
-     * Returns `[]` when PersonManager is unavailable, the user has no Person
-     * record, no record lists them, or the lookup throws.
+     * Returns `[]` when PersonManager is unavailable, there is no account by
+     * that username, no record lists them, or the lookup throws. An account
+     * missing its identity record gets it here (#2037).
+     *
+     * `ctx` is who is asking (#2018), decided by PersonManager's door: a user
+     * about themselves under `profile-manage`, about anyone else under
+     * `contact-read`; core's own work passes the system context. A refusal is
+     * thrown as `ContactRefusedError`, never answered as "no roles".
      */
-    resolveUserRoles(username: string): Promise<string[]>;
+    resolveUserRoles(ctx: ActorContext, username: string): Promise<string[]>;
     /**
      * The `required-aal` levels the OPERATOR set in their own config (#448,
      * #1523), as opposed to the shipped defaults. An operator's level that no
@@ -86,15 +96,26 @@ declare class RoleManager extends BaseManager {
      * `anonymous`) requires nothing beyond being signed in.
      */
     roleRequiredAal(): Record<string, 1 | 2 | 3>;
-    hasRole(username: string, roleName: string): Promise<boolean>;
-    /** Assign one role to an existing account, and record it (#1204). */
+    /** Whether `username` holds `roleName` now, asked by `ctx`; decided as {@link resolveUserRoles} (#2018). */
+    hasRole(ctx: ActorContext, username: string, roleName: string): Promise<boolean>;
+    /**
+     * Assign one role to an existing account, and record it (#1204). A role
+     * that cannot be given is refused (#2015): the error is thrown, admins are
+     * notified, and the attempt is recorded as a failed user-edit.
+     */
     assignRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
-    /** Remove one role from an existing account, and record it (#1204). */
+    /** Remove one role from an existing account, and record it (#1204); refused like `assignRole` when it cannot be done. */
     removeRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
     /**
      * Make the user's memberships go from `oldRoles` to `newRoles`. Used by
      * UserManager when an account is created or edited; the account write
      * records its own audit event, so this records none.
+     *
+     * All or nothing (#2015): when any change cannot be made, the ones already
+     * made are undone and a `RoleChangeError` is thrown, after it is logged as
+     * an error and admins are notified. That includes a change that cannot even
+     * be attempted: no PersonManager, no Person record for the username, or no
+     * anchor Organization.
      */
     applyRoleDiff(username: string, oldRoles: string[], newRoles: string[]): Promise<void>;
     /**
@@ -108,28 +129,67 @@ declare class RoleManager extends BaseManager {
      * a role change and is recorded as one, under the system context `ctx`,
      * deferred until the audit sink is up when this runs at boot.
      *
+     * #2015: each account gets the role or not. One that does not is recorded as
+     * a failed user-edit, and every miss is an error in the log and one error
+     * notification for admins naming the accounts to fix by hand. The boot goes
+     * on: nobody asked, so there is nobody to refuse.
+     *
      * @returns how many accounts were given the role (0 once it has been given)
      */
     grantToEveryAccountOnce(roleName: string, usernames: readonly string[], ctx: JobContext): Promise<number>;
     /**
      * Move every membership held by one Person `@id` to another (#1930): when
      * PersonManager joins an account to an existing person, the roles the
-     * account's person held go with the account. One write per role record;
-     * returns how many records changed. PersonManager's join records the change.
+     * account's person held go with the account. Returns how many records
+     * changed. PersonManager's join records the change. All or nothing (#2015).
      */
     moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
-    /** Remove a deleted account's Person from every role it held. */
-    removeAllMemberships(username: string): Promise<void>;
     /**
-     * Add the user's Person `@id` to the role record for (installOrg, roleName).
-     * Idempotent: a no-op when the Person is already a member.
-     *
-     * Failures are logged, not thrown — account writes must succeed even when
-     * role storage is degraded. #1027: every abandon path says why, because a
-     * silent one is indistinguishable from success.
+     * Remove a deleted account's Person from every role it held. All or nothing
+     * (#2015): when any removal fails the others are put back and it throws, so
+     * the account delete is refused. Returns the undo, for a delete that fails
+     * after this: it gives every role back. An account with no Person holds no
+     * role, so there is nothing to remove.
+     */
+    removeAllMemberships(username: string): Promise<() => Promise<void>>;
+    /** The roles `username` gains and loses, all or nothing; `notify` false lets a batch send one notice. */
+    private changeRoles;
+    /**
+     * The Person `@id` and anchor Organization a username's role changes need
+     * (#1027). Either missing refuses the change (#2015): an account must not
+     * be left without the role it was given, nor keep one it was meant to lose.
+     */
+    private membershipTarget;
+    /** One member change and its inverse. */
+    private memberChange;
+    /**
+     * Make each change in turn (#2015). When one fails, undo the ones made, in
+     * reverse, and throw. Returns the changes made, for a later undo.
+     */
+    private allOrNothing;
+    /** Undo `done`, newest first; returns the labels that could not be undone. */
+    private undoAll;
+    /**
+     * A role change that did not happen is always an error (operator,
+     * 2026-10-23): logged at error level, and an error notification for admins
+     * unless the caller sends one for a whole batch. Returns the error to throw.
+     */
+    private roleFailure;
+    /** An error notification for admins; a notification that cannot be sent is logged, never thrown. */
+    private reportToAdmins;
+    /** #2015: the membership queue's key for one role record. */
+    private membershipKey;
+    /**
+     * Make `personId` a member of the role record, or not, one change at a time
+     * per record (#2015). The record is read inside the queue, so a change never
+     * works from a member list another change has since replaced. A missing
+     * record is created in `createIn` for an add; with no `createIn` an add to a
+     * missing record throws, and a removal from one changes nothing. False,
+     * writing nothing, when the person already is (or is not) a member.
      */
-    private addMember;
-    private removeMember;
+    private setMember;
+    /** assignRole / removeRole: the change, recorded as a user-edit whether it happened or not (#1204, #2015). */
+    private recordedRoleChange;
     /**
      * The role record for (installOrg, namedPosition), created when missing.
      *

package/lib/src/managers/UserManager.d.ts

@@ -153,7 +153,7 @@ interface UserCreateInput {
 /**
  * User update input data
  */
-interface UserUpdateInput {
+export interface UserUpdateInput {
     email?: string;
     displayName?: string;
     password?: string;
@@ -166,6 +166,16 @@ interface UserUpdateInput {
     profilePage?: string;
     [key: string]: unknown;
 }
+/**
+ * A change worked out from the account as it is now (#2025), the function form
+ * of `updateUser`. It runs inside the account's key, is handed a copy of the
+ * account without the password hash (an add-on's own fields included, as
+ * `UserUpdateInput` allows them), and returns the fields to merge, or
+ * `undefined` to change nothing.
+ */
+export type UserUpdateFn = (current: Omit<User, 'password'> & {
+    [key: string]: unknown;
+}) => UserUpdateInput | undefined | Promise<UserUpdateInput | undefined>;
 /**
  * UserManager - Handles user authentication, authorization, and roles
  *
@@ -208,6 +218,8 @@ declare class UserManager extends BaseManager {
     private provider;
     private providerClass?;
     private passwordSalt?;
+    /** One read-merge-write at a time per account, keyed by the normalized username (#2025). */
+    private readonly accountWrites;
     /**
      * Creates a new UserManager instance
      *
@@ -328,6 +340,17 @@ declare class UserManager extends BaseManager {
     private withAccountRoles;
     /** `ngdpbase.user.account-roles`: the roles every account holds (#1539). */
     private accountRoles;
+    /**
+     * Every account has exactly one identity record, made by `createUser`
+     * (#2037). One that has none (written straight into the user store, or
+     * whose record was lost) gets it at boot, once, through PersonManager's
+     * door under the system context, each creation recorded as
+     * `contact-manage`. The identity records are listed once and only the
+     * missing ones are made, so a large user store costs one read. A failure
+     * is logged and the boot goes on: the role paths make the record when the
+     * account is next used (`getByUserIdentifier`).
+     */
+    private giveIdentityRecordsToAccountsWithout;
     /**
      * Accounts made before a role joined `ngdpbase.user.account-roles` get it
      * once, at boot (#1539) — RoleManager decides "once" and records each grant.
@@ -358,6 +381,15 @@ declare class UserManager extends BaseManager {
     upgradePasswordHash(username: string, newHash: string, legacy: boolean): Promise<void>;
     /** Count a completed sign-in on the account: last sign-in and sign-in count (#1758; AuthManager calls it for a sign-in, never a re-check). */
     recordSignIn(username: string): Promise<void>;
+    /** Run `task` inside the account's key: one read-merge-write at a time per account (#2025). Not re-entrant. */
+    private inAccountKey;
+    /**
+     * Read an account, change it and write it back, inside its key (#2025): for
+     * core's own bookkeeping (sign-in counters, the hash upgrade, the profile
+     * page), which is not an edit and is not recorded. False when there is no
+     * such account.
+     */
+    private patchAccount;
     /**
      * Check if a display name conflicts with existing page names or other users
      * @param {string} displayName - Display name to check
@@ -400,6 +432,12 @@ declare class UserManager extends BaseManager {
      * @returns {Promise<Omit<User, 'password'>>} Created user (without password)
      */
     createUser(userData: UserCreateInput, ctx: ActorContext): Promise<Omit<User, 'password'>>;
+    /**
+     * Take back an account whose roles could not be given (#2015): its Person,
+     * then the account. A failure here is an error in the log; the role failure
+     * that caused it is what the caller is told.
+     */
+    private undoAccountCreate;
     /**
      * Update user
      */
@@ -419,7 +457,31 @@ declare class UserManager extends BaseManager {
      * which accounts exist.
      */
     resetPasswordWithRecoveryWords(username: string, words: string, newPassword: string, ctx: ActorContext): Promise<boolean>;
-    updateUser(username: string, updates: UserUpdateInput, ctx: ActorContext): Promise<User>;
+    /**
+     * Change an account (#2025: one change at a time per account).
+     *
+     * `updates` is the fields to merge, or a function that works them out from
+     * the account as it is now: `(current) => updates`. The function runs inside
+     * the account's `KeyedSerial` key, between the read and the write, so two
+     * changes to one account never read the same old record. It gets a copy of
+     * the account without the password hash, and returns the fields to merge, or
+     * `undefined` to change nothing (nothing is written or recorded). It must not
+     * call `updateUser` for the same account: the key is not re-entrant.
+     * Either form is checked, applied and recorded the same way.
+     *
+     * Returns the account as written (as read, when nothing changed), without
+     * the password hash: the hash never leaves UserManager except to the
+     * password check (`storedPasswordHash`).
+     */
+    updateUser(username: string, updates: UserUpdateInput | UserUpdateFn, ctx: ActorContext): Promise<Omit<User, 'password'>>;
+    /**
+     * The steps of an account change that come after the write, outside the
+     * account's key: they reach other managers, which may change the account
+     * themselves.
+     */
+    private finishEdit;
+    /** Read, check and write one account change. Runs inside the account's key (#2025). */
+    private editAccount;
     /**
      * Delete user
      */
@@ -469,6 +531,8 @@ declare class UserManager extends BaseManager {
      * who changed it, so the record says why.
      */
     private personSyncContext;
+    /** Core's bookkeeping for an account write, the read of its roles included (#2018): the system context, saying what and who changed the account. */
+    private lifecycleContext;
     /**
      * Persist a Person record paired with a newly-created User. The install's
      * anchor org (when configured) is referenced via `memberOf`; without it

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

@@ -27,8 +27,15 @@ import type { PermissionSubject, JobSubject } from '../managers/UserManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Decision, DecisionRequest, Policy } from '../types/Policy.js';
 import { type RoleGrant } from '../utils/roleGrants.js';
+import { type ActorContext } from '../context/ActorContext.js';
 export declare const POLICIES_KEY = "ngdpbase.access.policies";
 export declare const POLICIES_ENABLED_KEY = "ngdpbase.access.policies.enabled";
+/**
+ * What `decide`, `permits` and `holds` take (#2022): the caller's own context
+ * — a request's `PermissionSubject` or a job's `JobContext` — or a subject
+ * already in decision form (`JobSubject`). A caller passes what it was given.
+ */
+type DecisionInput = ActorContext | JobSubject | null | undefined;
 export declare class PolicyDecisionPoint extends BaseManager {
     /**
      * A manager so every PEP can reach it through `engine.getManager`, the same
@@ -84,10 +91,11 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * of {@link decide} for a capability. It was `UserManager.hasPermission`
      * until #1431 step 14; the decision was already here, only the door moved.
      *
-     * Takes a `PermissionSubject` — the request's own identity, forwarded from
-     * `req.userContext` (WikiContext, ApiContext, ParseContext) or a
-     * `JobContext` for work with no request (#631). Roles arrive already
-     * resolved; the session middleware did that once per request.
+     * Takes the caller's context as it was given (#2022): a `PermissionSubject`
+     * — the request's own identity, forwarded from `req.userContext`
+     * (WikiContext, ApiContext, ParseContext), roles already resolved by the
+     * session middleware — or a `JobContext` for work with no request (#631),
+     * which the PDP turns into a subject itself. Never convert one first.
      *
      * #1173 Part B: the username-string overload this method once accepted is
      * gone. A string cannot carry `viaToken`, so the agent-token ceiling below
@@ -98,12 +106,13 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * separate question {@link userHoldsPermission} — "does the named user hold
      * this?" — which is a lookup about somebody else, not an authorisation.
      *
-     * @param subject - The identity being authorised, with `roles` resolved and
-     *                  `viaToken` present when a bearer token authenticated it.
+     * @param subject - The caller's context: the request's subject, with
+     *                  `viaToken` present when a bearer token authenticated it,
+     *                  or a job's context.
      * @param action - Action/permission to check (e.g., 'page-create', 'user-read')
      * @returns True if the subject may perform the action under current policy
      */
-    permits(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    permits(subject: DecisionInput, action: string): Promise<boolean>;
     /**
      * Does the subject HOLD this permission (#1635)? Policy alone — the
      * step-up freshness rule is not applied. A different question from
@@ -112,7 +121,7 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * person whose sign-in is not fresh still sees the way to the prompt that
      * makes it fresh. A door never asks this.
      */
-    holds(subject: PermissionSubject | JobSubject | null | undefined, action: string): Promise<boolean>;
+    holds(subject: DecisionInput, action: string): Promise<boolean>;
     /**
      * Step-up (#1525, #1635), decided here — in the one place every door asks —
      * rather than by routes in front of the doors. A permission marked
@@ -252,7 +261,7 @@ export declare class PolicyDecisionPoint extends BaseManager {
      *    time, not at enqueue time (#631, #1212).
      * 4. __The policies__, through `PolicyEvaluator`.
      */
-    decide(subject: PermissionSubject | JobSubject | null | undefined, request: DecisionRequest): Promise<Decision>;
+    decide(subject: DecisionInput, request: DecisionRequest): Promise<Decision>;
     /** `decide`, with the step-up rule applied or not — {@link holds} is the only caller that leaves it out. */
     private evaluate;
 }

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.
@@ -348,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
@@ -381,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
@@ -399,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;
     /**
@@ -425,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[]>;
@@ -445,7 +460,7 @@ 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).
      * Returns a decision object; decided=false means no front matter restriction — fall through.
@@ -462,10 +477,10 @@ declare class PolicyInformationPoint extends BaseManager {
      * 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 caller - the caller's context, as given (a job's included, #2022)
      * @param metadata - the page's current frontmatter
      */
-    audienceAdmits(userContext: UserContext | null | undefined, metadata: PageFrontmatter | null | undefined): Promise<boolean>;
+    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/Consent.js

@@ -0,0 +1,22 @@
+/**
+ * Consent to a site's documents (#1603): the shapes ConsentManager and its
+ * callers share, and what an add-on registers.
+ */
+/** Where a person is asked to accept (#1603): `?scope=` (core when absent) and `?returnTo=`. */
+export const CONSENT_PATH = '/consent';
+/** The scope of core's own documents, `ngdpbase.consent.documents`. */
+export const CORE_CONSENT_SCOPE = 'core';
+/**
+ * Thrown when a per-person add-on is turned on before its documents are
+ * accepted (#1603). `documents` names what is still to accept.
+ */
+export class ConsentRequiredError extends Error {
+    scope;
+    documents;
+    name = 'ConsentRequiredError';
+    constructor(scope, documents) {
+        super(`Turning ${scope} on needs its ${documents.join(' and ')} accepted first`);
+        this.scope = scope;
+        this.documents = documents;
+    }
+}

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/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';