@jwilleke/ngdpbase-types 5.31.0 → 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';

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/IdentityManager.d.ts

@@ -1,6 +1,6 @@
 import BaseManager, { type BackupFolder, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Person, PersonAffiliation, PersonChange, PersonInput } 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). */
@@ -162,6 +162,41 @@ declare class IdentityManager extends BaseManager {
      * 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.
+     */
+    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),
@@ -241,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/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

@@ -249,14 +249,35 @@ 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.
+     * 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.
      */
-    private assertEmailFree;
+    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
@@ -266,14 +287,6 @@ declare class UserManager extends BaseManager {
      * this on each such request.
      */
     reportSessionCookieWithheld(): void;
-    /**
-     * 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;
     /**
      * 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.
      *

package/lib/src/providers/databaseMigrations.js

@@ -87,6 +87,36 @@ const DATABASE_MIGRATIONS = [
         created_at TEXT NOT NULL
       )`);
         }
+    },
+    {
+        // #2072: requests for review. `details` is the request's JSON, which can
+        // be personal: ReviewManager writes rows only while this database is
+        // encrypted. A failed handler leaves the row `open`, with `failure` and
+        // `failed_at` saying why and when.
+        id: '20261025120000',
+        description: 'reviews: review_requests',
+        up: (db) => {
+            db.exec(`CREATE TABLE review_requests (
+        id TEXT PRIMARY KEY,
+        kind TEXT NOT NULL,
+        handler_id TEXT NOT NULL,
+        decide_permission TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        details TEXT NOT NULL,
+        status TEXT NOT NULL,
+        filed_at TEXT NOT NULL,
+        filed_by TEXT NOT NULL,
+        decided_at TEXT,
+        decided_by TEXT,
+        note TEXT,
+        outcome TEXT,
+        failed_at TEXT,
+        failure TEXT
+      )`);
+            db.exec('CREATE INDEX review_requests_by_status ON review_requests (status, filed_at)');
+            db.exec('CREATE INDEX review_requests_by_decided ON review_requests (decided_at)');
+        }
     }
 ];
 export default DATABASE_MIGRATIONS;

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

@@ -316,6 +316,16 @@ export interface ApplicationOrganizationConfig {
     '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;
+    /** #2073: the country (ISO 3166-1 alpha-2) a phone or address on /profile is read with until the user picks another */
+    'ngdpbase.application.persons.default-country': string;
+    /** #2073: minutes the link confirming a user's new email stays usable */
+    'ngdpbase.auth.email-change.ttl-minutes': number;
+    /** #2073: the least time between two email-change links for one account, in seconds */
+    'ngdpbase.auth.email-change.cooldown-seconds': number;
+    /** #2073: the most email-change links one account is sent per window */
+    'ngdpbase.auth.email-change.max-per-window': number;
+    /** #2073: that window, in minutes */
+    'ngdpbase.auth.email-change.window-minutes': number;
     /** #1930: the most results `OrganizationManager.search` returns when the caller gives no limit */
     'ngdpbase.application.organization.search.limit': number;
     /** Storage directory for OrganizationRole JSON files (one per (org, namedPosition) pair) */

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

@@ -39,7 +39,10 @@ export interface ContactPoint {
     /** 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;
+    /** E.164 (`+14155552671`) when written from /profile (#2073); add-ons may store other forms. */
     telephone?: string;
+    /** A phone's extension, digits, kept apart from `telephone` (#2073). */
+    extension?: string;
     url?: string;
     availableLanguage?: string[];
 }

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

@@ -111,3 +111,48 @@ export type PersonChange = Omit<PersonUpdate, 'affiliation'> & {
 export type PersonInput = PersonChange & {
     identifier?: string;
 };
+/** A phone as a user typed it (#2073): the number, the country to read it with, and an extension. */
+export interface PhoneInput {
+    number?: string;
+    /** ISO 3166-1 alpha-2; the configured default country when left out. Ignored for a number typed with a leading `+`. */
+    country?: string;
+    extension?: string;
+}
+/** An address as a user typed it (#2073). Every field empty removes the address. */
+export interface AddressInput {
+    streetAddress?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+    /** ISO 3166-1 alpha-2; the configured default country when left out. */
+    addressCountry?: string;
+}
+/**
+ * What `IdentityManager.updateContactDetails` takes (#2073): the parts of an
+ * identity record a user keeps on /profile. A part left out is not touched;
+ * a text given empty is removed.
+ */
+export interface ContactDetailsInput {
+    givenName?: string;
+    familyName?: string;
+    /** Phones by `contactType` (`home`, `mobile`, `business`, `other`, or any other kind). */
+    phones?: Array<PhoneInput & {
+        contactType: string;
+    }>;
+    /** The `emergency` ContactPoint: who to call, their phone and email. */
+    emergency?: {
+        name?: string;
+        email?: string;
+        phone?: PhoneInput;
+    };
+    /** The home address (`address`). */
+    address?: AddressInput;
+    /** The `mailing` PostalAddress in `contactPoint`. */
+    mailing?: AddressInput;
+    /** Languages, each a name ("Spanish") or a tag ("es"); stored as tags. */
+    knowsLanguage?: string[];
+    /** A photo: a web address. */
+    image?: string;
+    /** Links: web addresses. */
+    sameAs?: string[];
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Requests for review (#2072): what an add-on files, what a reviewer sees,
+ * and the handler that carries out an approved request. ReviewManager is the
+ * door; these are its shapes, declared once.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+/** Where a request is: waiting for a decision, or decided. A handler failure leaves it `open`. */
+export type ReviewStatus = 'open' | 'approved' | 'rejected';
+/** The two answers a reviewer gives. */
+export type ReviewDecision = 'approve' | 'reject';
+/** What an add-on files: `fileRequest(ctx, input)`. */
+export interface ReviewRequestInput {
+    /** What kind of request this is, `<slug>.<kind>` (`accommodation.new-owner`). Starts with the filing add-on's slug. */
+    kind: string;
+    /** What the request is about, in a few words a reviewer recognises (`Unit 12B`). */
+    subject: string;
+    /** One line saying what approving it does (`Add Pat Lee as an owner of unit 12B`). */
+    summary: string;
+    /** What the reviewer needs to decide, shown as label and value pairs; may be personal, so it is kept only in the encrypted database. */
+    details?: Record<string, string | number | boolean | null>;
+    /** The permission whose holders may decide it. Declared in `ngdpbase.permissions.definitions` and grantable; never a role name. */
+    decidePermission: string;
+    /** The handler that carries it out once approved, as registered with `host.registerReviewHandler` (`<slug>.<name>`). */
+    handlerId: string;
+}
+/** A request as the door hands it out. */
+export interface ReviewRequest {
+    id: string;
+    kind: string;
+    subject: string;
+    summary: string;
+    details: Record<string, string | number | boolean | null>;
+    decidePermission: string;
+    handlerId: string;
+    status: ReviewStatus;
+    /** ISO 8601, UTC. A screen shows it in the viewer's local time. */
+    filedAt: string;
+    /** The username of whoever filed it (`anonymous` for a public form). */
+    filedBy: string;
+    decidedAt: string | null;
+    decidedBy: string | null;
+    /** The reviewer's note, if they wrote one. */
+    note: string | null;
+    /** On approval: what the handler said it did. */
+    outcome: string | null;
+    /** The last time the handler failed, and why, while the request stays open. */
+    failedAt: string | null;
+    failure: string | null;
+}
+/** What a handler answers when it has carried out the request. */
+export interface ReviewHandlerResult {
+    /** What was done, in plain words, shown to reviewers (`Account created for Pat Lee and invitation sent`). */
+    summary: string;
+}
+/**
+ * Carries out an approved request, with the decider's context. Throw to say it
+ * was not done: the request stays open and the error's message is shown to
+ * reviewers as the reason, so write it for them.
+ */
+export type ReviewHandler = (request: ReviewRequest, ctx: ActorContext) => Promise<ReviewHandlerResult>;
+/** The door as `host.reviews` hands it to an add-on: the same calls, with `fileRequest` held to the add-on's own prefix. */
+export interface AddonReviews {
+    fileRequest(ctx: ActorContext, input: ReviewRequestInput): Promise<ReviewRequest>;
+    listOpen(ctx: ActorContext): Promise<ReviewRequest[]>;
+    get(ctx: ActorContext, id: string): Promise<ReviewRequest | null>;
+    decide(ctx: ActorContext, id: string, decision: ReviewDecision, note?: string): Promise<ReviewRequest>;
+}

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

@@ -17,7 +17,7 @@
  */
 import type { ShareGrant } from './Share.js';
 import type { ProxyClaim } from '../managers/UserManager.js';
-import type { SignInRecord, PendingConnection } from '../managers/AuthManager.js';
+import type { SignInRecord, PendingConnection, OutsideChoice } from '../managers/AuthManager.js';
 declare module 'express-session' {
     interface SessionData {
         csrfToken?: string;
@@ -45,6 +45,8 @@ declare module 'express-session' {
         pendingRedirect?: string;
         /** A verified outside identity no account has connected, waiting for the person to sign in another way (#1743). */
         pendingConnection?: PendingConnection;
+        /** #2073: an outside sign-in whose email several accounts share, waiting for the person to choose one. */
+        outsideChoice?: OutsideChoice;
         /**
          * Set at sign-in when the person has core terms to accept at their current
          * version (#1603); the consent gate holds the session to the prompt until

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

@@ -23,6 +23,10 @@
  *   unchanged, so an add-on never imports them from `dist/` (#1813);
  * - `keyedSerial()` returns a new `KeyedSerial`, core's own per-key queue, so
  *   an add-on's manager changes each of its records one at a time (#2065);
+ * - `reviews` is ReviewManager's door (#2072), with `fileRequest` held to this
+ *   add-on's own `<slug>.` kinds and handlers, and `registerReviewHandler`
+ *   registers only `<slug>.<name>` handlers, so one add-on can never file for,
+ *   or carry out, another's requests;
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -43,6 +47,7 @@ import { KeyedSerial } from './keyedSerial.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import type { IceReceiver, IceShim } from '../ice/types.js';
+import type { AddonReviews, ReviewHandler } from '../types/Review.js';
 import type { AddonManifest } from '../managers/AddonsManager.js';
 /** The values core offers an add-on, under the names they were imported as. */
 export interface AddonHost {
@@ -98,6 +103,20 @@ export interface AddonHost {
      * the read included. Not re-entrant: `fn` must not `run` the same key again.
      */
     readonly keyedSerial: () => KeyedSerial;
+    /**
+     * #2072: core's one way to review requests. `fileRequest(ctx, { kind,
+     * subject, summary, details, decidePermission, handlerId })` files one for
+     * the holders of `decidePermission` to decide; `kind` and `handlerId` must
+     * start with this add-on's slug. `listOpen`, `get` and `decide` are the
+     * reviewer's calls, each asked of the PDP with the caller's context.
+     */
+    readonly reviews: AddonReviews;
+    /**
+     * #2072: register the handler that carries out an approved request, as
+     * `<slug>.<name>`; any other prefix throws. It is called with the decider's
+     * context; throw to leave the request open with your message as the reason.
+     */
+    readonly registerReviewHandler: (handlerId: string, handler: ReviewHandler) => void;
     /**
      * #1979 (ICE, D6): register an import shim, as `<slug>.<shim.name>`. Call it
      * in `register`. Refused when the manifest's `shims` does not name it.

package/lib/src/utils/addonHost.js

@@ -23,6 +23,10 @@
  *   unchanged, so an add-on never imports them from `dist/` (#1813);
  * - `keyedSerial()` returns a new `KeyedSerial`, core's own per-key queue, so
  *   an add-on's manager changes each of its records one at a time (#2065);
+ * - `reviews` is ReviewManager's door (#2072), with `fileRequest` held to this
+ *   add-on's own `<slug>.` kinds and handlers, and `registerReviewHandler`
+ *   registers only `<slug>.<name>` handlers, so one add-on can never file for,
+ *   or carry out, another's requests;
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -93,6 +97,30 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         }
         return registry;
     };
+    const reviewDoor = () => {
+        const door = engine?.getManager('ReviewManager');
+        if (!door)
+            throw new Error('reviews are not available: this host was built without a site\'s ReviewManager');
+        return door;
+    };
+    const ownPrefix = (what, value) => {
+        if (typeof value !== 'string' || !value.startsWith(`${slug}.`)) {
+            const message = `Add-on '${slug}' may file only its own review requests: a ${what} starts '${slug}.'; '${String(value)}' does not`;
+            logger.error(`[addons] ${message}`);
+            throw new Error(message);
+        }
+    };
+    const reviews = {
+        fileRequest: async (ctx, input) => {
+            ownPrefix('kind', input?.kind);
+            ownPrefix('handler', input?.handlerId);
+            return reviewDoor().fileRequest(ctx, input);
+        },
+        listOpen: async (ctx) => reviewDoor().listOpen(ctx),
+        get: async (ctx, id) => reviewDoor().get(ctx, id),
+        decide: async (ctx, id, decision, note) => reviewDoor().decide(ctx, id, decision, note)
+    };
+    Object.freeze(reviews);
     const hostAddonAuditEventName = (name) => {
         const checked = addonAuditEventName(name);
         refuseUndeclared(slug, name, declared);
@@ -123,6 +151,8 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         refusedNodeMessage,
         isAtLeast,
         zonedParts,
-        keyedSerial: () => new KeyedSerial()
+        keyedSerial: () => new KeyedSerial(),
+        reviews,
+        registerReviewHandler: (handlerId, handler) => reviewDoor().registerHandler(slug, handlerId, handler)
     });
 }

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

@@ -54,6 +54,10 @@ 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";
+    /** A user's new email was confirmed by its emailed link and saved (#2073). Names only, never an address */
+    readonly EMAILCHANGE_CONFIRM: "emailchange-confirm";
+    /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
+    readonly EMAILCHANGE_REQUEST: "emailchange-request";
     /** 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 */
@@ -132,6 +136,14 @@ export declare const AUDIT_EVENT: {
     readonly REAUTH_PROMPT: "reauth-prompt";
     /** Step-up: the user re-authenticated, with the factor used */
     readonly REAUTH_SUCCESS: "reauth-success";
+    /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    readonly REVIEW_APPROVED: "review-approved";
+    /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
+    readonly REVIEW_FAILED: "review-failed";
+    /** A request was filed for review (#2072): who filed it, its id, kind, the add-on handler and the permission whose holders decide; never its summary or details */
+    readonly REVIEW_FILED: "review-filed";
+    /** A request was rejected (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    readonly REVIEW_REJECTED: "review-rejected";
     /** Page search; not recorded, read volume */
     readonly SEARCH_PAGE: "search-page";
     /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */

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

@@ -61,6 +61,10 @@ 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',
+    /** A user's new email was confirmed by its emailed link and saved (#2073). Names only, never an address */
+    EMAILCHANGE_CONFIRM: 'emailchange-confirm',
+    /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
+    EMAILCHANGE_REQUEST: 'emailchange-request',
     /** 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 */
@@ -139,6 +143,14 @@ export const AUDIT_EVENT = {
     REAUTH_PROMPT: 'reauth-prompt',
     /** Step-up: the user re-authenticated, with the factor used */
     REAUTH_SUCCESS: 'reauth-success',
+    /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    REVIEW_APPROVED: 'review-approved',
+    /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
+    REVIEW_FAILED: 'review-failed',
+    /** A request was filed for review (#2072): who filed it, its id, kind, the add-on handler and the permission whose holders decide; never its summary or details */
+    REVIEW_FILED: 'review-filed',
+    /** A request was rejected (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    REVIEW_REJECTED: 'review-rejected',
     /** Page search; not recorded, read volume */
     SEARCH_PAGE: 'search-page',
     /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */

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

@@ -0,0 +1,9 @@
+/**
+ * Language names and tags for an identity record's `knowsLanguage` (#2073).
+ * The names are the runtime's own (`Intl.DisplayNames`), so no list is kept
+ * here: every two-letter ISO 639-1 code the runtime can name.
+ */
+/** The tag for a language given by name ("Spanish") or tag ("es"), ignoring case; null when unknown. */
+export declare function languageTag(given: string): string | null;
+/** A stored tag as a name ("es" → "Spanish"); the tag itself when the runtime has no name for it. */
+export declare function languageName(tag: string): string;

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

@@ -0,0 +1,38 @@
+/**
+ * Phone numbers and countries for identity records (#2073).
+ *
+ * Phones are stored in E.164 (`+14155552671`), the extension apart. What a
+ * user types is read with the country chosen beside it; a number typed with
+ * a leading `+` keeps its own country code. Parsing and the per-country
+ * rules are libphonenumber-js's (Google's libphonenumber metadata, kept
+ * current by its maintainers); country names are the runtime's own
+ * (`Intl.DisplayNames`), so no list is kept here.
+ */
+/** A country the dropdowns offer: its ISO 3166-1 alpha-2 code, its name, and its calling code. */
+export interface CountryOption {
+    code: string;
+    name: string;
+    callingCode: string;
+}
+/** Every country libphonenumber knows, by English name. Built once. */
+export declare function countryOptions(): CountryOption[];
+/** `code` (any case) when it is a country the dropdowns offer, else null. */
+export declare function knownCountry(code: unknown): string | null;
+/**
+ * What the user typed, as E.164 with any extension typed after it
+ * (`x12`, `ext. 12`), read with `country` unless it starts with `+`.
+ * Null when it is not a valid number.
+ */
+export declare function toE164(typed: string, country: string): {
+    telephone: string;
+    extension: string | null;
+} | null;
+/**
+ * A stored number shown back: its national form and its country, for the
+ * dropdown. A value that is not E.164 (written before #2073, or by an
+ * add-on) is shown as stored, with `fallback` as its country.
+ */
+export declare function localForm(stored: string, fallback: string): {
+    number: string;
+    country: string;
+};

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

@@ -32,8 +32,10 @@ export type UserCreateFailureReason =
 'username-taken'
 /** The display name collides with something that already exists. */
  | 'display-name-conflict'
-/** The email address already belongs to another account (#1748). */
- | 'email-taken';
+/** An account holding the admin role would share its email (#2073). */
+ | 'admin-email-shared'
+/** The account would set its own email without the emailed link (#2073). */
+ | 'email-unconfirmed';
 /**
  * A user-creation failure with a reason a caller can branch on.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.31.0",
+  "version": "5.32.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",