@jwilleke/ngdpbase-types 5.29.0 → 5.30.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -39,9 +39,13 @@ export type { default as ImportManager } from '../../src/managers/ImportManager.
 export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, IceUpload, IceSource, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } from '../../src/ice/types.js';
 export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
 export type { User, UserPreferences } from '../../src/types/User.js';
-export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
+export type { default as AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';
+export type { default as IdentityManager, LinkOfferOutcome } from '../../src/managers/IdentityManager.js';
+export type { 
+/** @deprecated Renamed `IdentityManager` (#2038); this alias goes after one release. */
+default as PersonManager } from '../../src/managers/IdentityManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
-export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
+export type { Organization, OrganizationInput, OrganizationUpdate, ContactPoint, ContactPointEntry, PostalAddress } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
 export type { default as RoleManager } from '../../src/managers/RoleManager.js';

package/lib/src/context/JobContext.d.ts

@@ -60,7 +60,10 @@ export interface JobContext {
     viaToken?: AgentTokenGrant;
     /** The share the requesting call presented, when it did (#1222). Carried for the same reason. */
     viaShare?: ShareGrant;
-    /** The proxy grant the requesting call acted under, when it did (#1762). Carried for the same reason: a job never runs as the represented person unbounded. */
+    /**
+     * The proxy grant the requesting call acted under, when it did (#1762). Carried for the same reason: a job never runs as the represented user unbounded.
+     * Never with its `keyHandle` (#2047): a job carries no key of any kind, so it reaches no key copy and none is written to a run record ({@link withoutKeyHandle}).
+     */
     viaProxy?: ProxyClaim;
     /** The address the requesting call came from (#1179), when there was one. Provenance for the record. */
     ipAddress?: string;
@@ -96,6 +99,13 @@ export declare const ANONYMOUS_USERNAME = "Anonymous";
  * string, so `viaToken` comes along instead of being dropped.
  */
 export declare function jobContextFromRequest(identity: RequestIdentity | null | undefined, now?: Date): JobContext;
+/**
+ * A job context with no key handle in it (#2047). `jobContextFromRequest`
+ * already leaves the handle out; the job manager also passes every context it
+ * stores through this, so a context built by hand cannot carry a key copy's
+ * handle into a job or onto disk.
+ */
+export declare function withoutKeyHandle(ctx: JobContext): JobContext;
 /**
  * A request-origin context that also says why (#1179).
  *

package/lib/src/context/JobContext.js

@@ -54,11 +54,25 @@ export function jobContextFromRequest(identity, now = new Date()) {
         origin: 'request',
         ...(identity?.viaToken ? { viaToken: identity.viaToken } : {}),
         ...(identity?.viaShare ? { viaShare: identity.viaShare } : {}),
-        ...(identity?.viaProxy ? { viaProxy: identity.viaProxy } : {}),
+        ...(identity?.viaProxy ? { viaProxy: proxyClaimForJob(identity.viaProxy) } : {}),
         ...(identity?.ipAddress ? { ipAddress: identity.ipAddress } : {}),
         requestedAt: now.toISOString()
     };
 }
+/** The proxy claim without its key handle (#2047): the actor, grant and scopes stay for the ceiling and the record. */
+function proxyClaimForJob(claim) {
+    const { keyHandle: _dropped, ...kept } = claim;
+    return kept;
+}
+/**
+ * A job context with no key handle in it (#2047). `jobContextFromRequest`
+ * already leaves the handle out; the job manager also passes every context it
+ * stores through this, so a context built by hand cannot carry a key copy's
+ * handle into a job or onto disk.
+ */
+export function withoutKeyHandle(ctx) {
+    return ctx.viaProxy?.keyHandle === undefined ? ctx : { ...ctx, viaProxy: proxyClaimForJob(ctx.viaProxy) };
+}
 /**
  * A request-origin context that also says why (#1179).
  *

package/lib/src/context/bootActions.js

@@ -64,7 +64,9 @@ export function attributedTo(ctx) {
             origin: ctx.origin,
             reason: ctx.reason ?? null,
             requestedAt: ctx.requestedAt,
-            ...proxyMeta
+            // #2059: the delegation a request-origin job was queued under, by kind,
+            // with the same precedence as a request's own record (`actorOf`).
+            ...(ctx.viaToken ? { delegated: 'token' } : ctx.viaShare ? { delegated: 'share' } : proxyMeta)
         }
     };
 }

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

@@ -38,6 +38,7 @@ import type { Aal, AuthProvider, AuthInitiateContext, AuthVerifyCredentials, Phi
 import { type OutsideProviderIcon } from '../providers/OidcAuthProvider.js';
 import { type PasskeyRelyingParty } from '../providers/PasskeyAuthProvider.js';
 import { type CredentialKind, type CredentialRecord } from '../providers/BaseCredentialsProvider.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import { type AuditEventName } from '../utils/auditEventNames.js';
 import { type ScopeDescription } from '../utils/permissionCatalog.js';
 import type { Request } from 'express';
@@ -360,6 +361,32 @@ export type ProxyGrantSide = {
 };
 /** Where a signed-in person chooses whom to act for, and switches back (#1762 slice 4). */
 export declare const ACTING_FOR_PATH = "/account/acting-for";
+/** Where an invitation link opens (#2049): `GET` shows it, `POST` uses it. */
+export declare const INVITATION_PATH = "/invitation";
+/** Where an invited user sets up their sign-in after the link signs them in (#2049). */
+export declare const ACCOUNT_SETUP_PATH = "/account/setup";
+/** How many days an invitation link stays usable (#2049); read on every call. */
+export declare const INVITATION_TTL_KEY = "ngdpbase.auth.invitation.ttl-days";
+/** An invitation as an administrator sees it (#2049): never the link or its token. */
+export interface InvitationView {
+    id: string;
+    /** The account invited. */
+    username: string;
+    /** Who sent it. */
+    createdBy: string;
+    /** RFC 3339. */
+    createdAt: string;
+    /** RFC 3339: after this the link does nothing. */
+    expiresAt: string;
+}
+/** What sending an invitation came to (#2049); `reason` is plain words for the administrator. */
+export type InviteOutcome = {
+    outcome: 'sent';
+    invitation: InvitationView;
+} | {
+    outcome: 'email-unavailable' | 'send-failed' | 'not-invitable';
+    reason: string;
+};
 /**
  * Why a session started or stopped acting for someone (#1762 slice 4), as the
  * `proxy-switch` record's `reason` says it: the person chose a grant, chose
@@ -1166,6 +1193,83 @@ declare class AuthManager extends BaseManager {
      * the one that started the session. Null when the result is no sign-in.
      */
     reauthenticated(signIn: SignInRecord | undefined, result: AuthenticateResult): SignInRecord | null;
+    /** How long an invitation link stays usable: `ngdpbase.auth.invitation.ttl-days`, read on every call. */
+    invitationTtlMs(): number;
+    /**
+     * Why no invitation can be sent on this site now, in plain words for the
+     * administrator, or null when one can: email set up and working, an
+     * explicit site address for the link, and the credentials store open.
+     */
+    invitationsUnavailable(): string | null;
+    /** Sending, resending and cancelling an invitation is creating an account's way in: `user-create` (#2049). */
+    private mayInvite;
+    /** The live and expired invitation rows of the store, or none while it is closed. */
+    private invitationRows;
+    /**
+     * Why `username` cannot be invited, in plain words, or null when they can:
+     * an active account of this site, with an email address, no password, and
+     * never signed in. An account with a way in needs no invitation.
+     */
+    private notInvitable;
+    /**
+     * Send `username` an invitation (#2049): an email with a one-time link to
+     * set up their sign-in. Needs `user-create` (throws `Permission denied`).
+     * A new invitation replaces any earlier one, whose link stops working
+     * (resend). Recorded first, as `invitation-send` (refuse on failure), so no
+     * link exists that the audit log does not know of. When email cannot be
+     * sent the answer says so and nothing is kept; a send that fails removes
+     * the link again, recorded as `invitation-cancel` with reason `not-sent`.
+     * The message goes through EmailManager with the caller's context.
+     */
+    inviteUser(ctx: ActorContext, username: string): Promise<InviteOutcome>;
+    /**
+     * Cancel `username`'s invitation (#2049): its link stops working. Needs
+     * `user-create` (throws `Permission denied`). Recorded first, as
+     * `invitation-cancel` (refuse on failure). False when none was waiting.
+     */
+    cancelInvitation(ctx: ActorContext, username: string): Promise<boolean>;
+    /**
+     * The invitations waiting to be used, for the administrator's user list
+     * (#2049). Reading is not a change: it asks whether the caller holds
+     * `user-read`. Expired ones are removed first, each recorded as
+     * `invitation-expire`.
+     */
+    listInvitations(ctx: ActorContext): Promise<InvitationView[]>;
+    /** The live invitation a link's token names, or null: unknown, used, or expired (an expired one is removed, recorded). */
+    private liveInvitation;
+    /**
+     * Who an invitation link is for, to show before it is used (#2049), or
+     * null. Opening the link changes nothing (mail scanners open links): the
+     * page's button posts to `useInvitation`, behind the session's CSRF token.
+     */
+    invitationFor(token: unknown): Promise<{
+        username: string;
+        displayName: string;
+        expiresAt: string;
+    } | null>;
+    /**
+     * Use an invitation link (#2049): spend it, then sign its user in once
+     * through `completeSignIn` (a new session; the terms prompt first when
+     * terms are waiting), at AAL1 as an email link, so a role above that
+     * steps down as for any such sign-in. Returns where to go next
+     * (`ACCOUNT_SETUP_PATH`, or the terms prompt on the way there), or null
+     * when the link is unknown, used, expired, or its account is turned off.
+     *
+     * The row's removal is the single-use gate: the store deletes in memory
+     * before it writes, so of two requests with one link exactly one sees
+     * true. Recorded as `invitation-use`; the sign-in itself as
+     * `authentication-success`, method `invitation`.
+     */
+    useInvitation(req: Request, token: unknown): Promise<string | null>;
+    /** Remove every invitation past its end date, each recorded as `invitation-expire`. */
+    private sweepInvitations;
+    private expireInvitation;
+    /** End one invitation the caller may end: recorded first (`invitation-cancel`, refuse), then removed. */
+    private endInvitation;
+    /** An invitation record: `user` who acted (the sender, the canceller, the system), `resource` the account invited. Never the token. */
+    private auditInvitation;
+    /** `invitation-use`: the invited user, before any session exists, from the request's address and browser. */
+    private recordInvitationUse;
     private pendingSignIns;
     private approvalTokens;
     private enrolTokens;
@@ -1241,6 +1345,13 @@ declare class AuthManager extends BaseManager {
      * scanner opens links too.
      */
     approvalDetails(token: string, opener?: ApprovalVisitor): Promise<ApprovalDetails | null>;
+    /**
+     * `at` as `username` reads it: in their own time zone (their `timezone`
+     * preference, else `ngdpbase.default.timezone`), locale and clock, with the
+     * zone named (#1532). For a message sent to them, where no page script can
+     * show it in local time; the approval request and an invitation (#2049).
+     */
+    private localTimeFor;
     /**
      * What an approval request says about a waiting sign-in (#1532), one source
      * for the message and the page: the site's name, when it was asked in the

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

@@ -124,6 +124,8 @@ export declare function isCompanionOf(filename: string, documentFilename: string
  * and the Backup help page list the same.
  */
 export declare const NEVER_IN_A_BACKUP: readonly string[];
+/** The backup entry a registered manager's part is recorded under (#2038): its name, unless it was renamed. */
+export declare function managerEntryName(registered: string): string;
 /** The backup document entry, and the site restore part, an add-on's files are recorded under (#1985). */
 export declare function addonEntryName(slug: string): string;
 /**
@@ -575,6 +577,10 @@ declare class BackupManager extends BaseManager {
      */
     restoreFromFile(ctx: ActorContext, backupPath: string, options?: RestoreOptions): Promise<RestoreResults>;
     private restoreFromFileNow;
+    /** The registered managers, by the entry each is recorded under in a backup (#2038), in registration order. */
+    private registeredEntries;
+    /** The manager a backup entry belongs to (#2038), or undefined when this site has none. */
+    private managerFor;
     /** Whether this site's manager of that name stages its restore (#1876), or its entry is declared folders (#1985). */
     private restoresStaged;
     /**

package/lib/src/managers/BackupManager.js

@@ -61,7 +61,8 @@ const RESTORE_LABELS = {
     BackgroundJobManager: 'scheduled-job state',
     AttachmentManager: 'attachment files',
     RoleManager: 'role membership',
-    PersonManager: 'persons',
+    // IdentityManager's entry keeps its old name (#2038, MANAGER_ENTRY_NAMES).
+    PersonManager: 'identity records (of users and contacts)',
     OrganizationManager: 'organizations',
     FootnoteManager: 'footnotes on public pages',
     CommentManager: 'comments on public pages',
@@ -83,6 +84,24 @@ const ADDON_ENTRY_NAMES = {
     calendar: 'CalendarDataManager',
     feeds: 'FeedManager'
 };
+/**
+ * A core manager renamed after its entry was first written keeps that entry
+ * (#2038): IdentityManager was PersonManager, and its part is still recorded
+ * as `PersonManager` in the backup document and the site restore record, so
+ * an old backup restores and an older site can restore a new one. Keyed by
+ * the registered name; an entry is a stored name, never renamed.
+ */
+const MANAGER_ENTRY_NAMES = {
+    IdentityManager: 'PersonManager'
+};
+/** The backup entry a registered manager's part is recorded under (#2038): its name, unless it was renamed. */
+export function managerEntryName(registered) {
+    return Object.hasOwn(MANAGER_ENTRY_NAMES, registered) ? MANAGER_ENTRY_NAMES[registered] : registered;
+}
+/** The registered manager a backup entry belongs to (#2038): the inverse of {@link managerEntryName}. */
+function registeredNameOf(entry) {
+    return Object.entries(MANAGER_ENTRY_NAMES).find(([, e]) => e === entry)?.[0] ?? entry;
+}
 /** The backup document entry, and the site restore part, an add-on's files are recorded under (#1985). */
 export function addonEntryName(slug) {
     return ADDON_ENTRY_NAMES[slug] ?? `addon:${slug}`;
@@ -99,7 +118,7 @@ export function applyStagedPartsAtStart(engine, manager, declared) {
     const configManager = engine?.getManager?.('ConfigurationManager');
     if (!configManager)
         return null;
-    return applyDeclaredPartsAtStart(manager, declared, configManager);
+    return applyDeclaredPartsAtStart(managerEntryName(manager), declared, configManager);
 }
 /** The site restore manifest's file, as configured; a module function for the start, before BackupManager exists (#1986). */
 function manifestFileOf(engine) {
@@ -526,7 +545,7 @@ class BackupManager extends BaseManager {
                 managers: {}
             };
             // Get all manager names from engine
-            const managerNames = this.engine.getRegisteredManagers();
+            const managerNames = this.registeredEntries();
             logger.info(`📋 Found ${managerNames.length} registered managers`);
             // #1723: a manager may write its own files (the databases) beside the
             // document; they share its stem and are pruned with it.
@@ -550,7 +569,7 @@ class BackupManager extends BaseManager {
                     continue;
                 }
                 try {
-                    const manager = this.engine.getManager(managerName);
+                    const manager = this.managerFor(managerName);
                     const parts = declared.get(managerName) ?? [];
                     if (!manager && parts.length === 0) {
                         logger.warn(`⚠️  Manager not found: ${managerName}`);
@@ -1318,7 +1337,7 @@ class BackupManager extends BaseManager {
                     continue;
                 }
                 try {
-                    const manager = this.engine.getManager(managerName);
+                    const manager = this.managerFor(managerName);
                     if (!manager) {
                         logger.warn(`⚠️  Manager not found: ${managerName}, skipping`);
                         results.skipped.push(managerName);
@@ -1361,11 +1380,19 @@ class BackupManager extends BaseManager {
             throw error;
         }
     }
+    /** The registered managers, by the entry each is recorded under in a backup (#2038), in registration order. */
+    registeredEntries() {
+        return this.engine.getRegisteredManagers().map(managerEntryName);
+    }
+    /** The manager a backup entry belongs to (#2038), or undefined when this site has none. */
+    managerFor(entry) {
+        return this.engine.getManager(registeredNameOf(entry));
+    }
     /** Whether this site's manager of that name stages its restore (#1876), or its entry is declared folders (#1985). */
     restoresStaged(name) {
         if (this.declaredFor(name).length > 0)
             return true;
-        const manager = this.engine.getManager(name);
+        const manager = this.managerFor(name);
         return typeof manager?.restoreIsStaged === 'function' && manager.restoreIsStaged();
     }
     /**
@@ -1384,7 +1411,7 @@ class BackupManager extends BaseManager {
     }
     /** What a manager declares, and an add-on's folders recorded under the same entry (#1985). */
     declaredFor(name, forBackup = false) {
-        const manager = this.engine.getManager(name);
+        const manager = this.managerFor(name);
         let own = [];
         try {
             own = typeof manager?.backupFolders === 'function' ? manager.backupFolders() : [];
@@ -1396,7 +1423,7 @@ class BackupManager extends BaseManager {
     }
     /** Every entry with declared folders or files, in registration order, add-ons' after (#1985). */
     declaredParts(options = {}) {
-        const names = [...this.engine.getRegisteredManagers(), ...this.addonParts().map((a) => a.entry)];
+        const names = [...this.registeredEntries(), ...this.addonParts().map((a) => a.entry)];
         const out = new Map();
         for (const name of names) {
             if (out.has(name) || name === 'BackupManager')
@@ -1492,7 +1519,7 @@ class BackupManager extends BaseManager {
                     await stageDeclaredParts(name, declared, backupData.managers[name], restoreOptions);
                     continue;
                 }
-                await this.engine.getManager(name).restore(backupData.managers[name], restoreOptions);
+                await this.managerFor(name).restore(backupData.managers[name], restoreOptions);
             }
             // #1876: the instance .env, BackupManager's own part; applied at the very start of the process.
             const env = backupData.managers.BackupManager?.data?.env;
@@ -1729,7 +1756,7 @@ class BackupManager extends BaseManager {
     }
     /** The managers on this site whose restore is staged (#1876), in registration order: what a site restore stages. */
     stagedManagerNames() {
-        const names = this.engine.getRegisteredManagers().filter((name) => this.restoresStaged(name));
+        const names = this.registeredEntries().filter((name) => this.restoresStaged(name));
         // #1985: an add-on's files under an entry no manager of that name has (`addon:<slug>`).
         for (const { entry } of this.addonParts())
             if (!names.includes(entry))
@@ -1750,7 +1777,7 @@ class BackupManager extends BaseManager {
             .filter((name) => name !== 'DatabaseManager' || databases?.isEnabled?.() !== false)
             .map(restoreLabel);
         const notRestored = Object.keys(RESTORE_LABELS)
-            .filter((name) => name !== 'BackupManager' && this.engine.getManager(name) && !this.restoresStaged(name))
+            .filter((name) => name !== 'BackupManager' && this.managerFor(name) && !this.restoresStaged(name))
             .map(restoreLabel);
         return { restored, notRestored: [...notRestored, ...NEVER_IN_A_BACKUP] };
     }

package/lib/src/managers/{PersonManager.d.ts → IdentityManager.d.ts}

@@ -11,8 +11,12 @@ export interface LinkOfferDetails {
 /** The outcome of offering a sign-up link (#1930). */
 export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' | 'failed';
 /**
- * PersonManager — canonical core record for persons (#617), and the door for
- * contacts (#1930).
+ * IdentityManager — the identity record of every digital identity, user or
+ * contact (#617), and the door for them (#1930). Named PersonManager until
+ * #2038; `getManager('PersonManager')` still answers with it for one release
+ * (`MANAGER_ALIASES` in `src/core/Engine.ts`). What is stored keeps its
+ * "person" names: `data/persons/`, `ngdpbase.application.persons.*`, the
+ * `Person` types, `person:<uuid>`, the `person-*` audit actions.
  *
  * A person may have an account or not. Each account has exactly one person
  * (`identifier` = the username); a person with no account has the identifier
@@ -20,14 +24,14 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * the account lifecycle under a system context.
  *
  * The door: `create`, `update`, `delete`, `get`, `list`, `search` and
- * `linkAccount` take the caller's context first and ask the PDP: `contact-read`
- * to list, search or get; `contact-manage` to change (`linkAccount` also `user-edit`). Each change is recorded as
- * the `contact-manage` audit event. A refusal throws `ContactRefusedError`.
+ * `linkAccount` take the caller's context first and ask the PDP: `identity-read`
+ * to list, search or get; `identity-manage` to change (`linkAccount` also `user-edit`). Each change is recorded as
+ * the `identity-manage` audit event. A refusal throws `ContactRefusedError`.
  *
  * Every lookup takes the caller's context too (#2018): `getById`,
  * `getByIdentifier` and `getByUserIdentifier`. A user reads their own identity
  * record, and `update` changes it, under `profile-manage`; anyone else's needs
- * `contact-read` / `contact-manage`. Core's own reads (RoleManager resolving
+ * `identity-read` / `identity-manage`. Core's own reads (RoleManager resolving
  * roles on every request, UserManager's account lifecycle) pass the system
  * context, allowed without a policy evaluation (`requireRecordAccess`).
  *
@@ -40,8 +44,8 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * `getByUserIdentifier(ctx, username)` returns a user's identity record and
  * makes it when the user has none (#2037): every user has exactly one.
  */
-declare class PersonManager extends BaseManager {
-    readonly description = "Canonical Person records (#617)";
+declare class IdentityManager extends BaseManager {
+    readonly description = "Identity records of users and contacts (#617)";
     private provider;
     private providerClass?;
     /** `ngdpbase.application.persons.storagedir`, resolved at start: what a backup copies (#1876). */
@@ -65,7 +69,7 @@ declare class PersonManager extends BaseManager {
     getProvider(): PersonProvider | null;
     /**
      * One identity record by `@id` (#2018): the caller's own under
-     * `profile-manage`, anyone else's under `contact-read`, core's own work
+     * `profile-manage`, anyone else's under `identity-read`, core's own work
      * under the system context. A refusal throws `ContactRefusedError`.
      */
     getById(ctx: ActorContext, id: string): Promise<Person | null>;
@@ -80,9 +84,9 @@ declare class PersonManager extends BaseManager {
     getManagerStats(): Promise<ManagerStats>;
     /** True when the person has no account: its identifier is `person:<uuid>` (#1930). */
     static isAccountless(person: Pick<Person, 'identifier'>): boolean;
-    /** Every person, for a caller who may read contacts (`contact-read`). */
+    /** Every person, for a caller who may read contacts (`identity-read`). */
     list(ctx: ActorContext): Promise<Person[]>;
-    /** One person by `@id`: {@link getById}, the caller's own under `profile-manage`, anyone else's under `contact-read`. */
+    /** One person by `@id`: {@link getById}, the caller's own under `profile-manage`, anyone else's under `identity-read`. */
     get(ctx: ActorContext, id: string): Promise<Person | null>;
     /**
      * Persons whose name (`name`, `givenName`, `familyName`) or `email` contains
@@ -103,13 +107,13 @@ declare class PersonManager extends BaseManager {
     /**
      * Change a person's fields, affiliations included. `@id` and `identifier`
      * never change here. The caller's own identity record under
-     * `profile-manage`, anyone else's under `contact-manage` (#2018).
+     * `profile-manage`, anyone else's under `identity-manage` (#2018).
      */
     update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
     delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
      * An administrator joins a person who has no account to an account (#1930),
-     * for when the email differs or none was given. Asks `contact-manage` and
+     * for when the email differs or none was given. Asks `identity-manage` and
      * `user-edit`. The person keeps its `@id`; the account's own person, if it
      * has one, is folded in and removed.
      */
@@ -163,11 +167,11 @@ declare class PersonManager extends BaseManager {
      * store) gets it here, from the account's display name and email.
      *
      * The read is decided as {@link getByIdentifier} (#2018): a signed-in user's
-     * own under `profile-manage`, anyone else's under `contact-read`, core's own
+     * own under `profile-manage`, anyone else's under `identity-read`, core's own
      * work under the system context. Making the missing record is core's
      * bookkeeping, not the caller's contact management, so it goes through
      * {@link create} under the system context, naming the caller, and is
-     * recorded as `contact-manage`. One at a time per username, so two lookups
+     * recorded as `identity-manage`. One at a time per username, so two lookups
      * never make two records. Null when there is no account by that name.
      * Never a second record: a contact with the same email is left alone
      * (an administrator links it, {@link linkAccount}).
@@ -178,4 +182,4 @@ declare class PersonManager extends BaseManager {
     private normalizeProviderName;
 }
 export { ContactRefusedError } from '../utils/contactAccess.js';
-export default PersonManager;
+export default IdentityManager;

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

@@ -88,13 +88,13 @@ declare class OrganizationManager extends BaseManager {
      * problem actually bites.
      */
     getInstallOrg(): Promise<Organization | null>;
-    /** One organization by `@id`, for a caller who may read contacts (`contact-read`), or core's own work (#2018). */
+    /** One organization by `@id`, for a caller who may read contacts (`identity-read`), or core's own work (#2018). */
     getById(ctx: ActorContext, id: string): Promise<Organization | null>;
     /** One organization by its file name, decided as {@link getById} (#2018). */
     getByFile(ctx: ActorContext, filename: string): Promise<Organization | null>;
     /** #1006: how many organizations this instance holds. Count only. */
     getManagerStats(): Promise<ManagerStats>;
-    /** Every organization, for a caller who may read contacts (`contact-read`). */
+    /** Every organization, for a caller who may read contacts (`identity-read`). */
     list(ctx: ActorContext): Promise<Organization[]>;
     /** One organization by `@id`: {@link getById}. */
     get(ctx: ActorContext, id: string): Promise<Organization | null>;

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

@@ -45,7 +45,7 @@ declare class RoleManager extends BaseManager {
     backupFolders(): BackupFolder[];
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
-    /** One role record by `@id`: its members are identity records, so `contact-read`, or core's own work (#2018). */
+    /** One role record by `@id`: its members are identity records, so `identity-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[]>;
@@ -67,13 +67,13 @@ 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, there is no account by
+     * Returns `[]` when IdentityManager 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
+     * `ctx` is who is asking (#2018), decided by IdentityManager'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
+     * `identity-read`; core's own work passes the system context. A refusal is
      * thrown as `ContactRefusedError`, never answered as "no roles".
      */
     resolveUserRoles(ctx: ActorContext, username: string): Promise<string[]>;
@@ -114,7 +114,7 @@ declare class RoleManager extends BaseManager {
      * 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
+     * be attempted: no IdentityManager, no Person record for the username, or no
      * anchor Organization.
      */
     applyRoleDiff(username: string, oldRoles: string[], newRoles: string[]): Promise<void>;
@@ -139,9 +139,9 @@ declare class RoleManager extends BaseManager {
     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
+     * IdentityManager joins an account to an existing person, the roles the
      * account's person held go with the account. Returns how many records
-     * changed. PersonManager's join records the change. All or nothing (#2015).
+     * changed. IdentityManager's join records the change. All or nothing (#2015).
      */
     moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
     /**

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

@@ -343,9 +343,9 @@ declare class UserManager extends BaseManager {
     /**
      * 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
+     * whose record was lost) gets it at boot, once, through IdentityManager's
      * door under the system context, each creation recorded as
-     * `contact-manage`. The identity records are listed once and only the
+     * `identity-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`).
@@ -457,6 +457,16 @@ declare class UserManager extends BaseManager {
      * which accounts exist.
      */
     resetPasswordWithRecoveryWords(username: string, words: string, newPassword: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * A user's first password, chosen by themselves (#2049: after an
+     * invitation signed them in). Only for their own account, signed in as
+     * themselves (no token, share link or proxy), under `account-security`,
+     * and only while the account has no password: a password already set is
+     * changed on the profile, which asks for the current one. `false`,
+     * changing nothing, otherwise. The length rule is the route's, as for
+     * every password form. Recorded like any password change (`user-edit`).
+     */
+    setFirstPassword(username: string, newPassword: string, ctx: PermissionSubject): Promise<boolean>;
     /**
      * Change an account (#2025: one change at a time per account).
      *
@@ -517,6 +527,11 @@ declare class UserManager extends BaseManager {
     /**
      * Search users by username, displayName, or email (case-insensitive substring).
      * Optionally filter by role and active status.
+     *
+     * Decides `search-user` itself, with `ctx` (#2018): every user holds it as
+     * shipped, anonymous does not. A refusal throws `ContactRefusedError`. Core's
+     * own lookups (a notice's recipients, a role's holders) pass the system
+     * context with a reason, allowed without a policy evaluation.
      */
     searchUsers(query: string, options: {
         role?: string;
@@ -524,10 +539,10 @@ declare class UserManager extends BaseManager {
         activeOnly?: boolean;
     }, ctx: ActorContext): Promise<Omit<User, 'password'>[]>;
     /**
-     * The account lifecycle reaches PersonManager's door under a system context
+     * The account lifecycle reaches IdentityManager's door under a system context
      * (#1930): keeping an account's person in step with the account is core's
      * own bookkeeping, not the caller's contact management, so it never depends
-     * on the caller holding `contact-manage`. The reason names the account and
+     * on the caller holding `identity-manage`. The reason names the account and
      * who changed it, so the record says why.
      */
     private personSyncContext;
@@ -542,7 +557,7 @@ declare class UserManager extends BaseManager {
     private syncPersonOnCreate;
     /**
      * At sign-up, offer the new account a person with no account who has the
-     * same email (#1930): PersonManager mails an "Is this you?" link, and joins
+     * same email (#1930): IdentityManager mails an "Is this you?" link, and joins
      * them only when the account confirms. Skipped when email is off. Never
      * fails the account write.
      */

package/lib/src/providers/BaseCredentialsProvider.d.ts

@@ -24,8 +24,14 @@ export declare const CREDENTIALS_KEY_ENV = "NGDPBASE_CREDENTIALS_KEY";
  * represented, `subject` the grant id, `secret` the grant's terms as JSON
  * (whom it is for, the permissions, who made it, when it ends). Never a way
  * in; AuthManager reads and writes it only through its proxy-grant methods.
+ *
+ * `invitation` (#2049): a one-time link that lets a new user set up their
+ * sign-in — `username` the account invited, `subject` the SHA-256 of the
+ * link's token (the token itself is never stored), `secret` the terms as JSON
+ * (who sent it, when it ends). Not a sign-in method; AuthManager reads and
+ * writes it only through its invitation methods.
  */
-export type CredentialKind = 'passkey' | 'totp' | 'email' | 'sms' | 'device' | 'identity' | 'proxy';
+export type CredentialKind = 'passkey' | 'totp' | 'email' | 'sms' | 'device' | 'identity' | 'proxy' | 'invitation';
 export declare const CREDENTIAL_KINDS: readonly CredentialKind[];
 /** One credential, as stored. */
 export interface CredentialRecord {

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

@@ -43,6 +43,10 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * derived, never stored.
      */
     constructor(engine: WikiEngine);
+    /** Each `<policy id> <retired name>` already warned about (#2038): said once per process. */
+    private readonly warnedRetired;
+    /** Warn, once per policy and name, that a policy names a retired permission and what it is read as (#2038). */
+    private warnRetiredOnce;
     /**
      * The policies in force right now, highest priority first.
      *

package/lib/src/security/permissions.generated.d.ts

@@ -22,10 +22,10 @@ export type CorePermission =
  | 'comment-create'
 /** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
  | 'config-manage'
-/** Create, edit, delete and link contacts: persons (with or without an account) and organizations, and a person's affiliations, through PersonManager and OrganizationManager (#1930). Reading them is contact-read. Admins by default; an add-on grants it to its own roles in its own policy */
- | 'contact-manage'
-/** List, search and view contacts: persons (with or without an account) and organizations, and their affiliations, through PersonManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Admins and demo admins by default; an add-on grants it to its own roles in its own policy */
- | 'contact-read'
+/** Create, edit, delete and link identity records, of users and contacts alike, and organizations, and an identity's affiliations, through IdentityManager and OrganizationManager (#1930). Reading them is identity-read. Was contact-manage until #2038; a policy naming that is still read as this for one release. Admins by default; an add-on grants it to its own roles in its own policy */
+ | 'identity-manage'
+/** List, search and view identity records, of users and contacts alike, and organizations, and their affiliations, through IdentityManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Was contact-read until #2038; a policy naming that is still read as this for one release. Admins and demo admins by default; an add-on grants it to its own roles in its own policy */
+ | 'identity-read'
 /** Browse and view the media library (not delegated to anonymous visitors) */
  | 'media-read'
 /** Create new pages */

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

@@ -312,7 +312,7 @@ export interface ApplicationOrganizationConfig {
     'ngdpbase.application.persons.provider.default': string;
     /** Active Person provider class (lowercased; falls back to .default) */
     'ngdpbase.application.persons.provider': string;
-    /** #1930: the most results `PersonManager.search` returns when the caller gives no limit */
+    /** #1930: the most results `IdentityManager.search` returns when the caller gives no limit */
     'ngdpbase.application.persons.search.limit': number;
     /** #1930: minutes the emailed "Is this you?" sign-up link stays usable */
     'ngdpbase.application.persons.link-offer.ttl-minutes': number;

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

@@ -12,11 +12,15 @@
  * @see https://schema.org/Organization
  */
 /**
- * Schema.org PostalAddress (subset used by Organization)
+ * Schema.org PostalAddress (subset used by Organization/Person).
+ *
+ * In schema.org a PostalAddress is a ContactPoint, so it carries the
+ * ContactPoint fields too: a `contactPoint[]` entry may be one (a mailing or
+ * business address, with its `contactType`, `name` and `telephone`).
  *
  * @see https://schema.org/PostalAddress
  */
-export interface PostalAddress {
+export interface PostalAddress extends Omit<ContactPoint, '@type'> {
     '@type': 'PostalAddress';
     streetAddress?: string | null;
     addressLocality?: string | null;
@@ -32,11 +36,19 @@ export interface PostalAddress {
 export interface ContactPoint {
     '@type': 'ContactPoint';
     contactType?: string;
+    /** Who or what this contact point reaches, e.g. an agent's or an emergency contact's name (schema.org Thing.name). */
+    name?: string;
     email?: string;
     telephone?: string;
     url?: string;
     availableLanguage?: string[];
 }
+/**
+ * One `contactPoint[]` entry: a ContactPoint, or a PostalAddress (schema.org's
+ * ContactPoint subtype). Typed by `contactType` (`mailing`, `business`,
+ * `agent`, `emergency`, …); the home address stays in `address`.
+ */
+export type ContactPointEntry = ContactPoint | PostalAddress;
 /**
  * Canonical Organization record.
  *
@@ -62,8 +74,8 @@ export interface Organization {
     foundingDate?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (support, sales, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Contact points (support, sales, a mailing address, etc.) */
+    contactPoint?: ContactPointEntry[];
     /** Other URLs that identify this org (LinkedIn, Twitter, etc.) */
     sameAs?: string[];
     /** Optional legacy slug or external identifier */

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

@@ -15,7 +15,7 @@
  *
  * @see https://schema.org/Person
  */
-import type { PostalAddress, ContactPoint } from './Organization.js';
+import type { PostalAddress, ContactPointEntry } from './Organization.js';
 /**
  * One organization a person is affiliated with (#1930): schema.org
  * `affiliation`, with the person's role or title there when one is known.
@@ -51,8 +51,8 @@ export interface Person {
     email?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (work phone, mobile, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Everything but the home address: phones, a mailing or business address (a PostalAddress), an agent, an emergency contact; each typed by `contactType`. */
+    contactPoint?: ContactPointEntry[];
     /** ISO language tags this person knows */
     knowsLanguage?: string[];
     /** Profile/avatar image URL */
@@ -70,7 +70,7 @@ export interface Person {
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
 /**
- * What a caller gives `PersonManager.create` (#1930): the person's fields.
+ * What a caller gives `IdentityManager.create` (#1930): the person's fields.
  * `identifier` is left out for a person with no account (one is generated);
  * UserManager passes the account's username when it creates the person for a
  * new account.

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

@@ -2,7 +2,7 @@
  * Storage seam for Person records (#617)
  *
  * File system is the v1 default. Future providers (LDAP, external directory)
- * implement the same interface and register without touching PersonManager.
+ * implement the same interface and register without touching IdentityManager.
  */
 import type { BaseProvider } from './Provider.js';
 import type { Person, PersonUpdate } from './Person.js';
@@ -20,7 +20,7 @@ export interface PersonProvider extends BaseProvider {
     create(person: Person): Promise<Person>;
     /**
      * Write the whole record in place of the one with the same `@id` (#1930).
-     * The only write that may change `identifier`: PersonManager uses it to join
+     * The only write that may change `identifier`: IdentityManager uses it to join
      * a person to an account.
      */
     replace(person: Person): Promise<Person>;

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

@@ -54,10 +54,18 @@ export declare const AUDIT_EVENT: {
     readonly CONSENT_GRANT: "consent-grant";
     /** 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";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
+    /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    readonly IDENTITY_MANAGE: "identity-manage";
+    /** Invitation cancelled (#2049): an administrator cancelled it or sent a new one, the email could not be sent, or the account was deleted; the link stops working */
+    readonly INVITATION_CANCEL: "invitation-cancel";
+    /** Invitation expired (#2049): the link was not used in time and was removed */
+    readonly INVITATION_EXPIRE: "invitation-expire";
+    /** Invitation sent (#2049): a one-time link emailed to a new user to set up their sign-in; user is who sent it, resource the account invited. A credential nobody knows exists is the worst case, so it is recorded before the link exists */
+    readonly INVITATION_SEND: "invitation-send";
+    /** Invitation used (#2049): the invited user opened their link and was signed in once; the link is spent */
+    readonly INVITATION_USE: "invitation-use";
     /** A background job finished successfully */
     readonly JOB_COMPLETED: "job-completed";
     /** A background job failed */

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

@@ -61,10 +61,18 @@ export const AUDIT_EVENT = {
     CONSENT_GRANT: 'consent-grant',
     /** 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',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
+    /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    IDENTITY_MANAGE: 'identity-manage',
+    /** Invitation cancelled (#2049): an administrator cancelled it or sent a new one, the email could not be sent, or the account was deleted; the link stops working */
+    INVITATION_CANCEL: 'invitation-cancel',
+    /** Invitation expired (#2049): the link was not used in time and was removed */
+    INVITATION_EXPIRE: 'invitation-expire',
+    /** Invitation sent (#2049): a one-time link emailed to a new user to set up their sign-in; user is who sent it, resource the account invited. A credential nobody knows exists is the worst case, so it is recorded before the link exists */
+    INVITATION_SEND: 'invitation-send',
+    /** Invitation used (#2049): the invited user opened their link and was signed in once; the link is spent */
+    INVITATION_USE: 'invitation-use',
     /** A background job finished successfully */
     JOB_COMPLETED: 'job-completed',
     /** A background job failed */

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

@@ -139,13 +139,26 @@ export interface TokenInput extends CommonInput {
     /** Only meaningful for `revoke`; ignored otherwise. */
     revokedBy?: string;
 }
-export interface AttachmentInput extends CommonInput {
-    op: AttachmentOp;
+/**
+ * What an attachment record says about the file. A file in an ENCRYPTED store
+ * is recorded by its id and the store only (#2048): its name, its page and its
+ * size are the store's to keep sealed, so the record carries none of them.
+ */
+export type AttachmentDetail = {
     attachmentId: string;
     filename: string;
     pageName?: string | null;
     sizeBytes?: number | null;
-}
+} | {
+    attachmentId: string;
+    sealedStore: {
+        owner: string;
+        store: string;
+    };
+};
+export type AttachmentInput = CommonInput & {
+    op: AttachmentOp;
+} & AttachmentDetail;
 /**
  * Build the audit event for a page create, edit, rename, or link rewrite.
  *

package/lib/src/utils/auditEvents.js

@@ -145,18 +145,17 @@ export function buildPageViewAuditEvent(input) {
  * unattended destruction is the case someone reviewing the log is looking for.
  */
 export function buildAttachmentAuditEvent(input) {
-    const { op, attachmentId, filename, pageName, sizeBytes, viaToken } = input;
+    const { op, attachmentId, viaToken } = input;
     const who = whoOf(input);
-    const metadata = {
-        attachmentId,
-        filename,
-        ...tokenMetadata(viaToken),
-        ...who.metadata
-    };
-    if (pageName)
-        metadata.pageName = pageName;
-    if (typeof sizeBytes === 'number')
-        metadata.sizeBytes = sizeBytes;
+    const metadata = 'sealedStore' in input
+        ? { attachmentId, owner: input.sealedStore.owner, store: input.sealedStore.store, sealed: true, ...tokenMetadata(viaToken), ...who.metadata }
+        : { attachmentId, filename: input.filename, ...tokenMetadata(viaToken), ...who.metadata };
+    if (!('sealedStore' in input)) {
+        if (input.pageName)
+            metadata.pageName = input.pageName;
+        if (typeof input.sizeBytes === 'number')
+            metadata.sizeBytes = input.sizeBytes;
+    }
     const severity = op === 'delete'
         ? (viaToken ? 'high' : 'medium')
         : (viaToken ? 'medium' : 'low');

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

@@ -1,11 +1,11 @@
 /**
  * The contacts door's one decision and its one record (#1930).
  *
- * PersonManager and OrganizationManager are the enforcement points for
+ * IdentityManager and OrganizationManager are the enforcement points for
  * contacts. Both ask the PDP the same two questions with the caller's
- * context: `contact-read` to list, search or view, `contact-manage` to
+ * context: `identity-read` to list, search or view, `identity-manage` to
  * create, change, delete or link; and both record each change as the
- * `contact-manage` audit event. That rule lives here once, so the two doors
+ * `identity-manage` audit event. That rule lives here once, so the two doors
  * cannot drift (operator, 2026-10-20).
  *
  * A refusal is thrown as {@link ContactRefusedError}, carrying the decision.
@@ -15,7 +15,7 @@
  *
  * 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
+ * `profile-manage`, anyone else's under `identity-read` / `identity-manage`, and
  * core's own reads under the system context without a policy evaluation, so
  * resolving roles on every request stays cheap.
  */
@@ -27,8 +27,8 @@ type EngineLike = {
 };
 /** What a contacts door asks: `read` to list, search or view; `manage` to change. */
 export declare const CONTACT_PERMISSION: {
-    readonly read: "contact-read";
-    readonly manage: "contact-manage";
+    readonly read: "identity-read";
+    readonly manage: "identity-manage";
 };
 /** A contacts door said no. `permission` is what was refused; `decision` is the PDP's answer. */
 export declare class ContactRefusedError extends Error {
@@ -38,7 +38,7 @@ export declare class ContactRefusedError extends Error {
 }
 /**
  * Throws {@link ContactRefusedError} unless `ctx` may do `kind` (`read` asks
- * `contact-read`, `manage` asks `contact-manage`), and each of `also` (a link
+ * `identity-read`, `manage` asks `identity-manage`), and each of `also` (a link
  * to an account also asks `user-edit`). A missing context or decision point
  * refuses: closed, never open.
  */
@@ -58,7 +58,7 @@ export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | nul
  * - 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`.
+ * - read or change any other record: `identity-read` / `identity-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).
@@ -67,6 +67,13 @@ export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | nul
 export declare function requireRecordAccess(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, record?: {
     identifier?: unknown;
 } | null): Promise<void>;
+/**
+ * A lookup of users (#2018): `UserManager.searchUsers` asks `permission`
+ * (`search-user`) with the caller's context, and throws
+ * {@link ContactRefusedError} on a refusal. Core's own work
+ * ({@link isSystemWork}) is allowed without a policy evaluation.
+ */
+export declare function requireLookupPermission(engine: EngineLike, ctx: ActorContext, permission: CorePermission): Promise<void>;
 /** What a contacts record says was done. Names fields, never their values. */
 export interface ContactChange {
     kind: 'person' | 'organization';
@@ -79,7 +86,7 @@ export interface ContactChange {
     via?: 'admin' | 'email';
 }
 /**
- * Record a contacts change as `contact-manage`, under the caller's context.
+ * Record a contacts change as `identity-manage`, under the caller's context.
  * `continue`: a lost record is counted, the change stands. A system context
  * goes through `recordSystemAction`, so the bootstrap admin's person, made
  * before the audit sink is up, is recorded once it is.

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

@@ -14,7 +14,7 @@
  */
 import { type PrivateStoreLayout } from './privateStorePath.js';
 import { type UserCatalog } from './privateStoreCatalogs.js';
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import type { LinkPublicKey, Lockbox } from './shareLockbox.js';
 export declare function unlockPrivateStores(sessionId: string, username: string, kek: Buffer): void;
 export declare function getSessionUserIndex(sessionId: string): UserCatalog | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.29.0",
+  "version": "5.30.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",