@jwilleke/ngdpbase-types 5.29.1 → 5.30.1

package/README.md

@@ -11,7 +11,7 @@ import type { AddonModule, AddonHost, WikiEngine } from '@jwilleke/ngdpbase-type
 import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwilleke/ngdpbase-types/testing';
 ```
 
-- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
+- The main entry is types only. Importing it at run time fails, on purpose. An add-on takes core's values from `host` (`AddonHost`: the request and audit helpers, the logger, `guardedFetch`, the egress tools, `isAtLeast`, `zonedParts`) and a manager's job from `engine.getManager` (such as `PageManager.pageUrl` or `PolicyDecisionPoint.usersHolding`); it never imports core's values ([#1813](https://github.com/jwilleke/ngdpbase/issues/1813)).
 - `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

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

@@ -23,8 +23,9 @@ export type { PermissionSubject } from '../../src/managers/UserManager.js';
 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 { AuditEvent } from '../../src/utils/auditEvents.js';
-export type { JobRunContext } from '../../src/managers/BackgroundJobManager.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';
 export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
@@ -36,10 +37,14 @@ export type { PageAction } from '../../src/utils/pageUrl.js';
 export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
 export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as ImportManager } from '../../src/managers/ImportManager.js';
-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 { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, 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, ContactPoint, ContactPointEntry, PostalAddress } from '../../src/types/Organization.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;
@@ -68,6 +71,15 @@ export interface JobContext {
     requestedAt: string;
     /** Why, for origins with no person to ask. Free text, for the audit record. */
     reason?: string;
+    /**
+     * The scheduled job this run acts as (#1999): its id. Set by
+     * BackgroundJobManager on a scheduled slot's context, never on a run
+     * started by hand. When a policy names the job (`{ "type": "job", "value":
+     * "<id>" }`), its decisions are made as `job:<id>`, holding only what such
+     * policies grant; when none does, as the system principal, as before. Only
+     * the system principal's context can act as a job.
+     */
+    job?: string;
 }
 /** The shape a request-bound context exposes; both WikiContext and ApiContext satisfy it. */
 export interface RequestIdentity {
@@ -96,6 +108,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).
  *
@@ -133,7 +147,9 @@ export function toPermissionSubject(ctx) {
         resolveRolesNow: true,
         ...(ctx.viaToken ? { viaToken: ctx.viaToken } : {}),
         ...(ctx.viaShare ? { viaShare: ctx.viaShare } : {}),
-        ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {})
+        ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {}),
+        // #1999: the job a scheduled run acts as, for the PIP to resolve.
+        ...(ctx.job ? { job: ctx.job } : {})
     };
 }
 /** One line for a log or an audit record: who, from where, and how. */

package/lib/src/context/bootActions.js

@@ -64,7 +64,11 @@ export function attributedTo(ctx) {
             origin: ctx.origin,
             reason: ctx.reason ?? null,
             requestedAt: ctx.requestedAt,
-            ...proxyMeta
+            // #1999: a scheduled run names the job it acts as on every row it records.
+            ...(ctx.job ? { job: ctx.job } : {}),
+            // #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/ice/fileHandling.d.ts

@@ -1,5 +1,26 @@
 import { type ZipReadLimits } from '../utils/zipArchive.js';
 import type { IceUpload } from './types.js';
+/**
+ * A file's media type by its extension (#2061): how the engine labels a file
+ * it unpacks from a zip, and how the folder import labels a file it reads.
+ * A typed table, not configuration: it states what each format is, which is
+ * not a site's choice. What a site decides is which types it takes, and that
+ * is already its attachment allow-list (and a receiver's `originals.types`).
+ */
+export declare const MEDIA_TYPE_BY_EXTENSION: Readonly<Record<string, string>>;
+/** A file's media type by its extension alone: {@link MEDIA_TYPE_BY_EXTENSION}, else `application/octet-stream`. */
+export declare function mediaTypeByExtension(name: string): string;
+/**
+ * The media type of a file unpacked from a zip (#2061): its extension's,
+ * checked against its bytes where that is cheap. JSON must start with `{` or
+ * `[` (NDJSON with `{`), XML with `<`; one that does not is
+ * `application/octet-stream`. Then the upload door's own rule
+ * (`resolveUploadMime`): bytes that show a type decide (an XML file with an
+ * `<?xml` prolog is `text/xml`), and a claim they do not bear out is
+ * `application/octet-stream`. So the type a receiver is handed is the type
+ * the door stores.
+ */
+export declare function memberMediaType(name: string, bytes: Buffer): string;
 /** A file's fingerprint: SHA-256 of its bytes, hex. */
 export declare function fingerprint(bytes: Buffer): string;
 /**
@@ -15,8 +36,9 @@ export declare function isNoise(filePath: string, patterns: readonly string[]):
 export declare function isZip(upload: IceUpload): boolean;
 /**
  * Unpack the zips among the uploads into the files they hold, named
- * `archive.zip/inner/path`. A nested zip is unpacked too. Everything else is
- * passed through. Limits are per archive (`ZipReadLimits`), so a small
+ * `archive.zip/inner/path`, each with its media type ({@link memberMediaType},
+ * #2061). A nested zip is unpacked too. Everything else is passed through,
+ * with the type its request gave it. Limits are per archive (`ZipReadLimits`), so a small
  * archive that expands enormously stops at the budget. An archive that cannot
  * be read is returned in `unreadable`, with why; the rest go on.
  */

package/lib/src/ice/originalKeep.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The allowance a keep at upload carries to the upload door (#2061).
+ *
+ * A receiver that keeps originals in its own encrypted vault (phr) declares
+ * the media types it keeps (`originals.types`). The site's attachment
+ * allow-list does not name them (FHIR JSON, C-CDA XML), so the door would
+ * refuse the keep. The exemption is narrow, and lives here, not in a flag:
+ *
+ * - the engine opens one {@link OriginalKeep} for one receiver, one user and
+ *   one `keepOriginal` call, and closes it when the call returns;
+ * - the receiver passes it to `AttachmentManager.uploadAttachment` as its
+ *   `keep` option, unchanged;
+ * - the door honours it only while it is open, and only for a file going
+ *   into that user's own vault of a system-category the receiver's add-on
+ *   declares ({@link keepAllowsInto}). Anywhere else it changes nothing.
+ *
+ * An object the engine did not open is never honoured, whatever it says.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import type { OriginalKeep, RegisteredReceiver } from './types.js';
+/** Open a keep for one call of `receiver.keepOriginal` with `ctx`. Close it with {@link closeOriginalKeep}. */
+export declare function openOriginalKeep(receiver: RegisteredReceiver, ctx: ActorContext): OriginalKeep;
+/** The call is over: the keep is honoured no more. */
+export declare function closeOriginalKeep(keep: OriginalKeep): void;
+/** Where an upload is going, as the door resolved it. */
+export interface KeepDestination {
+    /** Who is uploading: the request's username. */
+    uploader: string;
+    /** The vault's owner. */
+    owner: string;
+    /** The add-on whose system-category declares the vault (`StoreKind.owner`); null when no category does. */
+    vaultAddon: string | null;
+}
+/**
+ * Does this keep apply to this upload? Only an open keep, for a file going
+ * into its user's own vault of a system-category its receiver's add-on
+ * declares, uploaded by that user. A `false` leaves the upload exactly as
+ * any other: the site's allow-list decides.
+ */
+export declare function keepAllowsInto(keep: OriginalKeep | undefined, to: KeepDestination): boolean;

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

@@ -130,6 +130,34 @@ export interface IceOriginalChoices {
     allowed: OriginalChoice[];
     /** One of `allowed`. Default: `ngdpbase.import.engine.default-original` when allowed, else the first allowed. */
     default?: OriginalChoice;
+    /**
+     * The media types this receiver keeps (#2061), exactly, e.g.
+     * `['application/json', 'application/x-ndjson', 'text/xml']`: no wildcards.
+     * For a keep at upload into the receiver's own vault, the upload door
+     * allows these even when the site's attachment allow-list does not
+     * ({@link OriginalKeep}). Every other upload still uses the site's list.
+     */
+    types?: string[];
+}
+/**
+ * What a keep at upload carries to the upload door (#2061): the engine opens
+ * one for one receiver, one user and one call of its `keepOriginal`, and
+ * closes it when the call returns. Pass it on unchanged as the upload's
+ * `keep` option. The door honours only one the engine has open, and only
+ * for a file going into this user's own vault of a system-category the
+ * receiver's add-on declares: there it allows `types` beyond the site's
+ * attachment allow-list, and the file is always served as a download.
+ * Anywhere else it changes nothing.
+ */
+export interface OriginalKeep {
+    /** The receiver keeping, `<slug>.<name>`. */
+    readonly receiver: string;
+    /** The add-on that registered it: only a vault its own system-category declares. */
+    readonly addon: string;
+    /** The user the upload is for: only their own vault. */
+    readonly user: string;
+    /** The receiver's `originals.types`. */
+    readonly types: readonly string[];
 }
 /** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
 export interface IceCitation {
@@ -180,8 +208,12 @@ export interface IceReceiver {
     /**
      * Keep the original file itself (D11: phr keeps originals in its own
      * store). Without this, `keep` hands the original to the files receiver.
+     * `original.mediaType` is the engine's (#2061): the request's type for a
+     * file uploaded on its own, the engine's for one unpacked from a zip.
+     * `keep` is given for a keep at upload (`keepsEncrypted`): pass it to the
+     * upload door unchanged, as the upload's `keep` option.
      */
-    keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+    keepOriginal?(original: IceItem, ctx: ActorContext, keep?: OriginalKeep): Promise<ReceiveOutcome>;
     /**
      * `keepOriginal` writes into an encrypted store (phr's vault), which only a
      * request holding the user's unlocked key can write (#2034). The engine then

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

@@ -10,7 +10,8 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
 import type { User } from '../providers/BaseAttachmentProvider.js';
 import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
-import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
+import type { OriginalKeep } from '../ice/types.js';
 /**
  * Base attachment provider interface
  */
@@ -44,13 +45,7 @@ interface BaseAttachmentProvider {
     getProviderInfo(): {
         features: string[];
     };
-    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: {
-        originalName: string;
-        mimeType: string;
-        description: string;
-        author?: string;
-        pageName?: string;
-    }): Promise<StoreFileEntry>;
+    storeFileInStore(location: StoreFileLocation, bytes: Buffer, file: StoreFileInput): Promise<StoreFileEntry>;
     getFileInStore(location: StoreFileLocation, id: string): Promise<{
         entry: StoreFileEntry;
         bytes: Buffer;
@@ -104,6 +99,15 @@ export interface UploadOptions {
     private?: boolean;
     /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
     store?: string;
+    /**
+     * An import's keep at upload (#2061): the `OriginalKeep` the engine handed
+     * the receiver's `keepOriginal`, passed on unchanged. Honoured only while
+     * the engine holds it open, for a file going into its user's own vault of a
+     * system-category the receiver's add-on declares: there the receiver's
+     * declared types are allowed beyond the site's allow-list, and the file is
+     * served as a download. Anywhere else it changes nothing.
+     */
+    keep?: OriginalKeep;
 }
 /**
  * Mention object (WebPage reference)

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

@@ -282,6 +282,14 @@ declare class BackgroundJobManager extends BaseManager {
     private compileScheduled;
     /** A run's time limit: the job's own, else `fallback`, capped by `ngdpbase.jobs.max-timeout-ms` when set. */
     private timeoutFor;
+    /**
+     * The time zone the scheduler runs a schedule in when the schedule names
+     * none (#1998): `ngdpbase.default.timezone`, UTC when it is not set. Read
+     * each call, as the schedules are. An add-on's job passes it, with its
+     * `ctx.slot`, to `host.zonedParts` to learn the slot's local month or day.
+     * A schedule that names its own `tz` runs in that zone instead.
+     */
+    scheduleTimeZone(): string;
     private compile;
     /**
      * `ngdpbase.jobs.<id>.schedule` in place of the registered schedule. One

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] };
     }