@jwilleke/ngdpbase-types 5.30.1 → 5.32.0

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

@@ -24,6 +24,8 @@ export type { Decision } from '../../src/types/Policy.js';
 export type { PluginContext, PluginParams, PluginFormatters } from '../../src/managers/PluginManager.js';
 export type { SimplePlugin } from '../../src/plugins/types.js';
 export type { KeyedSerial } from '../../src/utils/keyedSerial.js';
+export type { AddonReviews, ReviewDecision, ReviewHandler, ReviewHandlerResult, ReviewRequest, ReviewRequestInput, ReviewStatus } from '../../src/types/Review.js';
+export type { default as ReviewManager, ReviewRefusedError, ReviewsUnavailableError, ReviewNotOpenError, ReviewInputError, ReviewHandlerFailedError } from '../../src/managers/ReviewManager.js';
 export type { AuditEvent } from '../../src/utils/auditEvents.js';
 export type { default as BackgroundJobManager, JobDefinition, JobResult, JobRunContext } from '../../src/managers/BackgroundJobManager.js';
 export type { default as DatabaseManager, AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
@@ -41,12 +43,12 @@ export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection,
 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 AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';
-export type { default as IdentityManager, LinkOfferOutcome } from '../../src/managers/IdentityManager.js';
+export type { default as IdentityManager, LinkOfferOutcome, AffiliationQuery, IdentitySearch, IdentityMatch } 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 { Person, PersonAffiliation, LegacyPersonAffiliation, PersonChange, PersonInput, PersonUpdate } from '../../src/types/Person.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/managers/AuthManager.d.ts

@@ -34,7 +34,7 @@ import type { BackupData, BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
-import type { Aal, AuthProvider, AuthInitiateContext, AuthVerifyCredentials, PhishingResistance, ViaToken } from '../providers/BaseAuthProvider.js';
+import type { Aal, AuthProvider, AuthInitiateContext, AuthVerifyCredentials, PhishingResistance, ReportedAssurance, ViaToken } from '../providers/BaseAuthProvider.js';
 import { type OutsideProviderIcon } from '../providers/OidcAuthProvider.js';
 import { type PasskeyRelyingParty } from '../providers/PasskeyAuthProvider.js';
 import { type CredentialKind, type CredentialRecord } from '../providers/BaseCredentialsProvider.js';
@@ -229,6 +229,26 @@ export interface PendingConnection {
     /** Where the sign-in that follows was going; a declined connection goes there. */
     returnTo?: string;
 }
+/**
+ * An outside sign-in whose verified email several accounts here share
+ * (#2073): held in the session while the person chooses which account, asked
+ * every time and never remembered (no identity is connected). Single use.
+ */
+export interface OutsideChoice {
+    providerId: string;
+    /** The provider's verified email. */
+    email: string;
+    /** The accounts on that email, by username, when the callback came back. */
+    choices: string[];
+    /** The provider's name, for the page. */
+    displayName: string;
+    /** What the provider reported about its own sign-in (#1633), kept for the level it counts for. */
+    reported: ReportedAssurance;
+    /** Where the sign-in was going. */
+    returnTo: string;
+    /** Epoch ms. */
+    expiresAt: number;
+}
 /** How an outside sign-in's callback ended (#1743), for the route to answer. */
 export type OutsideSignIn = 
 /** Signed in (`created`: an account was made for it first); `next` is where to go. */
@@ -241,6 +261,10 @@ export type OutsideSignIn =
     outcome: 'connect-first';
     error?: string;
 }
+/** #2073: several accounts share the verified email; held for the person to choose one (`outsideChoice`). */
+ | {
+    outcome: 'choose-account';
+}
 /** Refused; nothing says whether an account exists. */
  | {
     outcome: 'refused';
@@ -601,6 +625,22 @@ declare class AuthManager extends BaseManager {
     private createAccountFor;
     /** Delete an account created for an outside sign-in that could not be finished (#1743), through UserManager, which closes its access. */
     private removeCreatedAccount;
+    /**
+     * The accounts an outside sign-in to a shared email offers (#2073), for the
+     * page asking which; null when none is waiting, and an expired one is dropped.
+     */
+    outsideChoice(req: Request): {
+        displayName: string;
+        choices: string[];
+    } | null;
+    /**
+     * Finish an outside sign-in to a shared email (#2073): `account` must be one
+     * the sign-in offered, still hold that email, be active, and be allowed to
+     * use the provider. The choice is used once, connects nothing and is not
+     * remembered; the next sign-in asks again. A sign-in at AAL1 takes the
+     * second step, as any outside sign-in does (#1532).
+     */
+    finishOutsideChoice(req: Request, account: string): Promise<OutsideSignIn>;
     /**
      * The person's pending connection, for the sign-in page's notice and the
      * confirmation page; an expired one is dropped (#1743).
@@ -1273,6 +1313,10 @@ declare class AuthManager extends BaseManager {
     private pendingSignIns;
     private approvalTokens;
     private enrolTokens;
+    /** #2073: links confirming a user's new email, by token; one waiting per account. In memory: a restart drops them. */
+    private emailChangeTokens;
+    /** #2073: when each account's email-change links were sent, for the cooldown and the cap. In memory. */
+    private emailChangeSends;
     /** Mail can carry an email-link factor: a mail transport and an explicit base-url for the link. */
     private mailForLinks;
     private linkBase;
@@ -1390,6 +1434,52 @@ declare class AuthManager extends BaseManager {
     startEmailFactorEnrolment(ctx: PermissionSubject, username: string): Promise<'sent' | 'no-email' | 'unavailable' | 'already'>;
     /** Finish enrolling from the emailed link, by the same signed-in person. Single use. */
     confirmEmailFactorEnrolment(ctx: PermissionSubject, token: string): Promise<boolean>;
+    /**
+     * A user asks to change their own email (#2073, operator 2026-10-25): it
+     * changes only when they click a link sent to the new address. Until then
+     * the account keeps its old email. The link is single use, lasts
+     * `ngdpbase.auth.email-change.ttl-minutes` (60), is bound to the account and
+     * the new address, and replaces any link still waiting for that account. The
+     * old address, when there is one, is told a change was asked, with no link.
+     * Recorded as `emailchange-request`, naming the account, never an address.
+     *
+     * Only the account itself asks (its own context, signed in or just
+     * registered). `unavailable`: this site cannot send email now, so nothing
+     * is sent and an administrator can change it instead. `failed`: the send
+     * failed and no link is waiting. `unchanged`: the address is the one the
+     * account already has. `throttled`: the account asked too soon after its
+     * last link (`ngdpbase.auth.email-change.cooldown-seconds`, 60) or too often
+     * in the window (`ngdpbase.auth.email-change.max-per-window` links per
+     * `ngdpbase.auth.email-change.window-minutes`, 5 per 60); no mail is sent.
+     */
+    requestEmailChange(ctx: ActorContext, username: string, newEmail: string, via: 'profile' | 'registration'): Promise<'sent' | 'unchanged' | 'unavailable' | 'failed' | 'throttled'>;
+    /** The new address waiting to be confirmed for `username` (#2073), for the profile to show; null when none. */
+    pendingEmailChange(username: string): string | null;
+    /** What a confirmation link would change (#2073), for its page; null for an unknown, used or expired link. */
+    emailChangeOffer(token: string): {
+        username: string;
+        address: string;
+    } | null;
+    /**
+     * Confirm a new email from its emailed link (#2073). Single use: the link is
+     * spent first. The rules are checked again now: the account still exists,
+     * is on, and is not a shared account whose email only an administrator
+     * changes; and UserManager's own (an administrator's email is never
+     * shared). Saved through UserManager under the system context naming the
+     * account (the link is the authority), which keeps the identity record in
+     * step. Nobody is signed in. Recorded as `emailchange-confirm`. A user who
+     * had no email yet (just registered) is then offered their contact record,
+     * as at sign-up (#1930).
+     */
+    confirmEmailChange(token: string): Promise<{
+        outcome: 'changed';
+        username: string;
+    } | {
+        outcome: 'expired';
+    } | {
+        outcome: 'refused';
+        message: string;
+    }>;
     /**
      * Initiate a challenge-based auth flow (magic link email, OAuth redirect).
      */
@@ -1473,6 +1563,11 @@ declare class AuthManager extends BaseManager {
      * here would make an unbindable flow look like an attack.
      */
     getDeviceState(providerId: string, handle: string): string | null;
+    /**
+     * The accounts an emailed link to a shared address offers (#2073), by
+     * username, or null when the link names one account. Read without consuming.
+     */
+    getAccountChoices(providerId: string, handle: string): string[] | null;
     /**
      * Create the account behind a first-time credential (#1026, #1049).
      *

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

@@ -327,6 +327,15 @@ declare class BackgroundJobManager extends BaseManager {
     private startDrain;
     /** Every scheduled job, its state and its recent history. */
     listScheduledJobs(): Promise<ScheduledJobView[]>;
+    /**
+     * Every scheduled job's id and display name, as `listScheduledJobs` names
+     * them, without reading their state — for the admin roles page's Jobs part
+     * (#2067).
+     */
+    scheduledJobNames(): Array<{
+        id: string;
+        displayName: string;
+    }>;
     /**
      * One scheduled job as `listScheduledJobs` shows it, without its run
      * history, or null when no job of that id is scheduled. For a manager that

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

@@ -1,8 +1,31 @@
 import BaseManager, { type BackupFolder, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Person, PersonInput, PersonUpdate } from '../types/Person.js';
+import type { ContactDetailsInput, Person, PersonAffiliation, PersonChange, PersonInput } from '../types/Person.js';
 import type { PersonProvider } from '../types/PersonProvider.js';
 import { type ActorContext } from '../context/ActorContext.js';
+/** What `search(ctx, { affiliation })` looks for (#2039). */
+export interface AffiliationQuery {
+    /** The organization, by its `@id` (or `{ '@id' }`). */
+    memberOf: string | {
+        '@id': string;
+    };
+    /** The title, compared without case or surrounding spaces. Left out: any title, or none. */
+    title?: string;
+    /** True (the default): only affiliations held today, the first and last day included. False: any, past or future too. */
+    current?: boolean;
+}
+/** A search by affiliation (#2039). `limit` as for a text search; 0 is no limit. */
+export interface IdentitySearch {
+    affiliation: AffiliationQuery;
+    limit?: number;
+}
+/** One identity a search by affiliation found: a user or a contact, and the affiliations that matched. */
+export interface IdentityMatch {
+    identity: Person;
+    /** True for a user (an identity with credentials), false for a contact. */
+    hasCredentials: boolean;
+    affiliations: PersonAffiliation[];
+}
 /** What the confirmation page shows: the person the link would join. */
 export interface LinkOfferDetails {
     personName: string | null;
@@ -52,6 +75,7 @@ declare class IdentityManager extends BaseManager {
     private storageDir;
     private byIdentifierCache;
     private byIdCache;
+    private allCache;
     private metricsRef;
     /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
     private linkOffers;
@@ -59,6 +83,18 @@ declare class IdentityManager extends BaseManager {
     private readonly accountRecords;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Once, at start-up (#2039): every identity record still holding an
+     * affiliation in the old `{ organization, role? }` shape is rewritten as
+     * schema.org `OrganizationRole` (organization → `memberOf`, role →
+     * `roleName`), each rewrite recorded as `identity-manage` (`person-update`,
+     * field `affiliation`) under the system context. Nothing is dropped: any
+     * other field an old entry carries is kept on it. A record with no old entry
+     * is not touched, so a second start finds nothing to do. A record that
+     * cannot be rewritten is logged and left as it is; reads convert it anyway.
+     * Runs before any request, so nothing else writes these records meanwhile.
+     */
+    private convertLegacyAffiliations;
     /** `ngdpbase.application.persons.storagedir`, resolved: where the records are. */
     private configuredStorageDir;
     /**
@@ -79,6 +115,8 @@ declare class IdentityManager extends BaseManager {
      */
     getByIdentifier(ctx: ActorContext, identifier: string): Promise<Person | null>;
     private cachedById;
+    /** Every record, affiliations in the current shape, read from the provider once per write (#2039). */
+    private allRecords;
     private cachedByIdentifier;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
@@ -93,11 +131,20 @@ declare class IdentityManager extends BaseManager {
      * `query`, ignoring case; an empty query matches everyone. `accountless`
      * narrows to persons with no account. At most `limit` results
      * (`ngdpbase.application.persons.search.limit` by default).
+     *
+     * Or by affiliation (#2039): `search(ctx, { affiliation: { memberOf, title?,
+     * current? } })` finds every identity, users and contacts alike, with an
+     * affiliation to that organization: with that title when one is given, and
+     * held today (the first and last day included) unless `current` is false.
+     * Each match says whether it has credentials and which affiliations matched.
+     * Checked like any read of others' records: `identity-read`.
      */
     search(ctx: ActorContext, query: string, options?: {
         limit?: number;
         accountless?: boolean;
     }): Promise<Person[]>;
+    search(ctx: ActorContext, query: IdentitySearch): Promise<IdentityMatch[]>;
+    private searchByAffiliation;
     /**
      * Create a person. With no `identifier` the person has no account and gets
      * `person:<uuid>`. An `identifier` must be an existing account that has no
@@ -108,8 +155,48 @@ declare class IdentityManager 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 `identity-manage` (#2018).
+     *
+     * Affiliations (#2039): one with the site's own organization is a fact, so
+     * adding, changing or removing one also asks `identity-manage`, even on the
+     * caller's own record; one with any other organization is a claim, which a
+     * user may set on their own record under `profile-manage`.
+     */
+    update(ctx: ActorContext, id: string, patch: PersonChange): Promise<Person | null>;
+    /**
+     * The parts of an identity record a user keeps on `/profile` (#2073):
+     * given and family name, phones, the emergency contact, the home and
+     * mailing addresses, languages, a photo and links. A part left out of
+     * `input` is not touched; a text given empty is removed.
+     *
+     * - Phones are stored in E.164 with any extension apart (`extension`),
+     *   read with the country chosen beside each one (the configured default,
+     *   `ngdpbase.application.persons.default-country`, when none is given); a
+     *   number typed with a leading `+` keeps its own country code.
+     * - A phone, the emergency contact and the mailing address each take the
+     *   place of the record's first entry of their kind in `contactPoint`
+     *   (a ContactPoint by `contactType`, the mailing address as the
+     *   `mailing` PostalAddress), keeping that entry's other fields; every
+     *   other entry, an add-on's included, is kept as it is.
+     * - Languages are stored as tags ("es"), given by name or tag.
+     *
+     * Everything is checked before anything is written: a bad part throws
+     * {@link ContactDetailsInvalidError}, naming the part and the rule, never
+     * the value. The access and the record are {@link update}'s: the caller's
+     * own record under `profile-manage`, anyone else's under `identity-manage`,
+     * recorded as an `identity-manage` update naming the fields that changed.
+     * Nothing changed, nothing is written or recorded.
+     */
+    updateContactDetails(ctx: ActorContext, id: string, input: ContactDetailsInput): Promise<Person | null>;
+    /**
+     * Check `input` as {@link updateContactDetails} would, writing nothing
+     * (#2073): throws {@link ContactDetailsInvalidError} for a bad part. For a
+     * caller that writes something else first (the /profile card writes the
+     * account's name and email), so a bad detail refuses the whole save before
+     * anything is written.
      */
-    update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
+    checkContactDetails(input: ContactDetailsInput): void;
+    /** The country a phone or address is read with when none is chosen (#2073): `ngdpbase.application.persons.default-country`, `US` when unset or unknown. */
+    defaultCountry(): string;
     delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
      * An administrator joins a person who has no account to an account (#1930),
@@ -150,10 +237,18 @@ declare class IdentityManager extends BaseManager {
      */
     private join;
     /**
-     * Each affiliation names an organization that exists, looked up with the
-     * caller's context; `role` is trimmed text. Throws on any other shape.
+     * Each affiliation is a schema.org `OrganizationRole` (#2039): `memberOf` an
+     * organization that exists, an optional `roleName` (the title, trimmed free
+     * text) and optional `startDate` / `endDate` (`YYYY-MM-DD`, the start not
+     * after the end; a null end is an ongoing one, stored without it). An entry
+     * in the old `{ organization, role? }` shape is converted (one release, for
+     * add-ons not yet switched). Throws on any other shape. The organization is
+     * looked up as core's own check, under the system context, so a user may
+     * name one on their own record without `identity-read`.
      */
     private checkedAffiliations;
+    /** The site's own organization's `@id` (`OrganizationManager.getInstallOrg`): an affiliation with it is a fact (#2039). */
+    private siteOrganizationId;
     private configNumber;
     /**
      * Clear all caches. Called on every write — the simplest correct
@@ -181,5 +276,15 @@ declare class IdentityManager extends BaseManager {
     private getMetrics;
     private normalizeProviderName;
 }
+/**
+ * A contact detail given to {@link IdentityManager.updateContactDetails} is not valid (#2073); nothing was written.
+ * `part` is which detail (a phone's `contactType`, `emergency`, `address`, `mailing`, `knowsLanguage`, `image`,
+ * `sameAs`, `name`), `field` which box of it. The message names the rule, never the value given: it reaches URLs and logs.
+ */
+export declare class ContactDetailsInvalidError extends Error {
+    readonly part: string;
+    readonly field: string;
+    constructor(part: string, field: string, message: string);
+}
 export { ContactRefusedError } from '../utils/contactAccess.js';
 export default IdentityManager;

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

@@ -2,7 +2,7 @@ import BaseManager, { type BackupFolder, type ManagerStats } from './BaseManager
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Organization, OrganizationInput, OrganizationUpdate } from '../types/Organization.js';
 import type { OrganizationProvider } from '../types/OrganizationProvider.js';
-import type { Person } from '../types/Person.js';
+import type { Person, PersonAffiliation } from '../types/Person.js';
 import type { ActorContext } from '../context/ActorContext.js';
 /**
  * Subset of install-form data this manager needs to seed the anchor org.
@@ -107,13 +107,17 @@ declare class OrganizationManager extends BaseManager {
         limit?: number;
     }): Promise<Organization[]>;
     /**
-     * The people affiliated with an organization, read from each person's
-     * `affiliation` (#1930): the link is stored once, on the person. Each comes
-     * with the role they hold there, when one is given.
+     * The identities affiliated with an organization, users and contacts alike,
+     * read from each identity record's `affiliation` (#1930): the link is stored
+     * once, on the identity record. One entry per affiliation, each with its
+     * schema.org `OrganizationRole` (title as `roleName`, dates) (#2039), past
+     * and future ones included; `IdentityManager.search(ctx, { affiliation })`
+     * answers who holds one today. Searching identities is IdentityManager's,
+     * so this asks it.
      */
     people(ctx: ActorContext, organizationId: string): Promise<Array<{
         person: Person;
-        role?: string;
+        affiliation: PersonAffiliation;
     }>>;
     /**
      * Create an organization. `name` is required; `@id` defaults to the `url`,

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

@@ -0,0 +1,108 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { ActorContext } from '../context/ActorContext.js';
+import type { Decision } from '../types/Policy.js';
+import type { ReviewDecision, ReviewHandler, ReviewHandlerResult, ReviewRequest, ReviewRequestInput, ReviewStatus } from '../types/Review.js';
+export type { ReviewDecision, ReviewHandler, ReviewHandlerResult, ReviewRequest, ReviewRequestInput, ReviewStatus };
+/** The door said no: the caller may not decide (or see) this request. `decision` is the PDP's answer. */
+export declare class ReviewRefusedError extends Error {
+    readonly permission: string;
+    readonly decision: Decision;
+    readonly name = "ReviewRefusedError";
+    constructor(permission: string, decision: Decision);
+}
+/** Requests cannot be kept on this site right now; the message says why and how to fix it. */
+export declare class ReviewsUnavailableError extends Error {
+    readonly name = "ReviewsUnavailableError";
+}
+/** A request that is not open any more (decided already, or by someone else just now). */
+export declare class ReviewNotOpenError extends Error {
+    readonly name = "ReviewNotOpenError";
+}
+/** What was filed is not a valid request; the message says what is wrong. */
+export declare class ReviewInputError extends Error {
+    readonly name = "ReviewInputError";
+}
+/** The handler did not carry out an approved request; it stays open with `reason`. */
+export declare class ReviewHandlerFailedError extends Error {
+    readonly request: ReviewRequest;
+    readonly reason: string;
+    readonly name = "ReviewHandlerFailedError";
+    constructor(request: ReviewRequest, reason: string);
+}
+declare class ReviewManager extends BaseManager {
+    readonly description = "Requests for review: filed by add-ons, decided by the holders of a permission, carried out by the add-on (#2072)";
+    private db;
+    /** Why the door is closed, in plain words for an administrator; null while it is open. */
+    private unavailable;
+    /** Handler id → its add-on and the function. */
+    private readonly handlers;
+    /** One decision at a time per request, so two reviewers cannot both run its handler (#2015). */
+    private readonly serial;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /** Why requests cannot be filed or decided on this site, or null when they can. */
+    getUnavailableReason(): string | null;
+    /**
+     * Register the handler that carries out an approved request (#2072). Core
+     * calls this for an add-on through `host.registerReviewHandler`, which binds
+     * `owner` to the add-on's slug: the id must be `<owner>.<name>`, so one
+     * add-on can never register, or replace, another's. Registering the same id
+     * again (a restart of the add-on) replaces it.
+     */
+    registerHandler(owner: string, handlerId: string, run: ReviewHandler): void;
+    /** Forget an add-on's handlers (it was turned off): its open requests then fail to approve, saying so. */
+    unregisterHandlers(owner: string): void;
+    /**
+     * File a request. `ctx` is whoever the request is filed for (a public
+     * form's anonymous visitor included); filing asks no permission, because
+     * only add-on code reaches this, and an add-on files only for a handler it
+     * registered. Holders of `decidePermission` are told, without waiting.
+     *
+     * @throws ReviewInputError when the request is malformed: a kind or handler
+     *   outside the handler's add-on, an unknown or ungrantable permission, no
+     *   subject or summary, or details too large
+     * @throws ReviewsUnavailableError when requests cannot be kept here
+     */
+    fileRequest(ctx: ActorContext, input: ReviewRequestInput): Promise<ReviewRequest>;
+    /**
+     * The open requests `ctx` may decide, oldest first: each asked of the PDP
+     * by its permission, with the caller's context, never a role. At most
+     * `ngdpbase.reviews.list-limit` of them.
+     */
+    listOpen(ctx: ActorContext): Promise<ReviewRequest[]>;
+    /**
+     * One request, when `ctx` may decide it (open or decided); null when there
+     * is no such request.
+     *
+     * @throws ReviewRefusedError when the caller does not hold its permission
+     */
+    get(ctx: ActorContext, id: string): Promise<ReviewRequest | null>;
+    /**
+     * Approve or reject an open request, as `ctx`.
+     *
+     * - Reject: the request is marked rejected with the note; no handler runs.
+     * - Approve: the add-on's handler runs with `ctx`. When it returns, the
+     *   request is approved with the handler's summary. When it throws (or is
+     *   not registered), the request stays open with the reason and the time,
+     *   and {@link ReviewHandlerFailedError} is thrown so the reviewer sees it.
+     *
+     * @throws ReviewRefusedError when `ctx` may not decide it (hand to `enforceDeny`)
+     * @throws ReviewNotOpenError when it is decided already, or does not exist
+     */
+    decide(ctx: ActorContext, id: string, decision: ReviewDecision, note?: string): Promise<ReviewRequest>;
+    private open;
+    private settings;
+    private decider;
+    /** A whole number of 0 or more from the configuration, or the default. */
+    private number;
+    /** Throws {@link ReviewRefusedError} unless `ctx` may decide a request with this permission. No context or no PDP refuses. */
+    private requireDecider;
+    /** Remove decided requests older than `ngdpbase.reviews.retention-days` (0 keeps them). One indexed delete. */
+    private removeExpired;
+    /** Tell the holders of the request's permission. Never throws: a notice that cannot be sent is logged. */
+    private notifyDeciders;
+    /** The audit record: who, which request, its kind, handler and permission — names, never the summary, details or note. */
+    private record;
+}
+export default ReviewManager;

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

@@ -222,6 +222,8 @@ declare class UserManager extends BaseManager {
     private passwordSalt?;
     /** One read-merge-write at a time per account, keyed by the normalized username (#2025). */
     private readonly accountWrites;
+    /** Whether this process has already reported the withheld session cookie (#2071). */
+    private sessionCookieWithheldReported;
     /**
      * Creates a new UserManager instance
      *
@@ -247,22 +249,44 @@ declare class UserManager extends BaseManager {
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** An email as accounts are compared on it (#1748): trimmed, any case. No provider rules (Gmail dots, plus addressing, aliases). */
     private static emailKey;
-    /** The accounts holding this email, by username. Empty for no email. */
-    private accountsWithEmail;
     /**
-     * One email, one account (#1748): refuse to save an email another account
-     * already has. Not a setting. Thrown as `email-taken`, so registration shows
-     * its safe message and other routes their own.
-     */
-    private assertEmailFree;
-    /**
-     * Accounts that share an email, saved before #1748 refused it. They are not
-     * changed — an admin decides — but they are never silent: the manager is
-     * degraded (dashboard, `manager-state-change` audit), the log says which,
-     * and admins get a notification. Until resolved, a lookup by that email
-     * refuses (see `getUserByEmail`).
-     */
-    private reportDuplicateEmails;
+     * Every account holding this email (#2073): two or more accounts may share
+     * one (a couple, an older adult and a carer). Compared trimmed and in any
+     * case, with no provider rules (plus addressing is a different address).
+     * Empty for no email. Without the password hash.
+     */
+    getUsersByEmail(email: unknown): Promise<Array<Omit<User, 'password'>>>;
+    /**
+     * An account holding the admin role never shares its email (#2073, operator
+     * 2026-10-25), either way round: refused when `username` is or will be an
+     * administrator and another account holds `email`, and when another account
+     * holding `email` is an administrator. `roles` are the account's roles
+     * after the change, when the change sets them; otherwise its current ones
+     * are read. Throws `UserCreateError('admin-email-shared')`; the message names
+     * the accounts, for the log and an administrator, never for a visitor.
+     */
+    assertAdminEmailUnshared(username: string, email: unknown, ctx: ActorContext, roles?: readonly string[]): Promise<void>;
+    /**
+     * An account never sets its own email without the emailed link (#2073): a
+     * change of email made as the account itself is refused unless the caller
+     * holds `user-edit` (an administrator in Admin → Users is trusted). The
+     * link is AuthManager's (`requestEmailChange`, `confirmEmailChange`), which
+     * saves under the system context. Throws `UserCreateError('email-unconfirmed')`.
+     */
+    private assertEmailChangeAllowed;
+    /** The usernames of every account whose email another account holds too (#2073): the admins' marker on the user list. */
+    usernamesSharingAnEmail(): Promise<Set<string>>;
+    /** Whether an account other than `ownUsername` holds this email too (#2073): for the note at save and the admins' marker. */
+    isEmailShared(email: unknown, ownUsername: string | null): Promise<boolean>;
+    /**
+     * The session cookie is `secure` and a request came over plain http, so
+     * express-session sent no cookie and nobody can sign in (#2071). Sessions
+     * are this manager's, so the report is too: an error in the log, the
+     * dashboard's "needs your attention", and a notification for admins, once
+     * per process. Every later call is one boolean check, because app.ts calls
+     * this on each such request.
+     */
+    reportSessionCookieWithheld(): void;
     /**
      * Normalize provider name from configuration (lowercase) to class name (PascalCase)
      * @param {string} providerName - Provider name from configuration (e.g., 'fileuserprovider')

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

@@ -70,6 +70,5 @@ export declare class AuthentikBearerAuthProvider implements AuthProvider {
      * config.defaultRole — even with no group hits, user gets the default.
      */
     private mapGroupsToRoles;
-    private findUserByEmail;
     private deriveUniqueUsername;
 }

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

@@ -46,6 +46,8 @@ export interface AuthVerifyCredentials {
     password?: string;
     /** One-time token — used by MagicLinkAuthProvider */
     token?: string;
+    /** The account chosen for a link to a shared address (#2073) — used by MagicLinkAuthProvider. */
+    account?: string;
     /** OAuth `state` from the callback — used by OidcAuthProvider */
     state?: string;
     /** The browser-binding value from the caller's cookie (#1022 magic link, #1630 OAuth) */
@@ -207,6 +209,11 @@ export interface AuthProvider {
      * Must be read BEFORE `consumeToken()`, which deletes the entry.
      */
     getDeviceState?(handle: string): string | null;
+    /**
+     * The accounts a flow to a shared address offers (#2073), by username, or
+     * null when it names one account. Read without consuming.
+     */
+    accountChoices?(handle: string): string[] | null;
     /**
      * Create the account behind a first-time credential (#1049).
      *

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

@@ -67,6 +67,5 @@ export declare class CloudflareAccessAuthProvider implements AuthProvider {
      * config.defaultRole — even with no group hits, user gets the default.
      */
     private mapGroupsToRoles;
-    private findUserByEmail;
     private deriveUniqueUsername;
 }

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

@@ -16,6 +16,11 @@
  *
  * Tokens are in-memory only — lost on restart, acceptable for the default 15-min TTL.
  *
+ * A shared address (#2073): two or more accounts may hold one email. The link
+ * then names no account; the person opening it chooses one of the accounts on
+ * the address, and the link alone is enough for any of them (the mailbox is
+ * the shared trust, operator 2026-10-25).
+ *
  * @see AuthManager
  * @see BaseAuthProvider
  */
@@ -57,6 +62,13 @@ export declare class MagicLinkAuthProvider implements AuthProvider {
      * Does NOT consume the token — call consumeToken() after the session is created.
      */
     verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    /**
+     * The accounts a link to a shared address offers (#2073), by username, or
+     * null for a link to one account (or an unknown or expired one). Read
+     * without consuming, so the page asking which account can be shown.
+     */
+    accountChoices(token: string): string[] | null;
+    private liveEntry;
     /**
      * Delete the token and report whether THIS caller was the one that did.
      *