@jwilleke/ngdpbase-types 5.29.1 → 5.30.1

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

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

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

@@ -267,7 +267,8 @@ export type TakeoutImportReport = {
 export interface UsableReceiver {
     id: string;
     label?: string;
-    originals: Required<IceOriginalChoices>;
+    /** What the screen offers; the kept types (`types`, #2061) are the upload door's business, not the screen's. */
+    originals: Required<Omit<IceOriginalChoices, 'types'>>;
 }
 /**
  * Import Manager class
@@ -546,10 +547,6 @@ declare class ImportManager extends BaseManager {
      * @returns Stats about imported attachments
      */
     private importPageAttachments;
-    /**
-     * Get MIME type from file extension
-     */
-    private getMimeType;
     /**
      * Get file extensions to process based on options
      */

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

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

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

@@ -34,6 +34,13 @@ interface AccessContext {
  * policy naming it decides nothing (docs/access-policies.md).
  */
 export declare const RESOURCE_MATCHERS: Record<string, (pattern: string, pageName: string, attributes?: ResourceAttributes) => boolean>;
+/**
+ * How each policy subject type matches (#1999), one matcher per type. These
+ * are the only subject types a decision matches, and the only ones
+ * PolicyValidator accepts: a type with no matcher here would be a policy that
+ * grants nothing.
+ */
+export declare const SUBJECT_MATCHERS: Record<string, (value: string, userContext: UserContext | undefined) => boolean>;
 /**
  * The resource types configuration declares (#1504), for the evaluator and the
  * validator alike. When the key is not set at all — a configuration older than

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

@@ -45,7 +45,7 @@ declare class RoleManager extends BaseManager {
     backupFolders(): BackupFolder[];
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
-    /** One role record by `@id`: its members are identity records, so `contact-read`, or core's own work (#2018). */
+    /** One role record by `@id`: its members are identity records, so `identity-read`, or core's own work (#2018). */
     getById(ctx: ActorContext, id: string): Promise<Role | null>;
     getByOrgAndPosition(organizationId: string, namedPosition: string): Promise<Role | null>;
     listByMember(personId: string): Promise<Role[]>;
@@ -67,13 +67,13 @@ declare class RoleManager extends BaseManager {
      * The pseudo-roles `'Authenticated'` and `'All'` are NOT added here — the
      * caller adds those when constructing `userContext.roles`.
      *
-     * Returns `[]` when PersonManager is unavailable, there is no account by
+     * Returns `[]` when IdentityManager is unavailable, there is no account by
      * that username, no record lists them, or the lookup throws. An account
      * missing its identity record gets it here (#2037).
      *
-     * `ctx` is who is asking (#2018), decided by PersonManager's door: a user
+     * `ctx` is who is asking (#2018), decided by IdentityManager's door: a user
      * about themselves under `profile-manage`, about anyone else under
-     * `contact-read`; core's own work passes the system context. A refusal is
+     * `identity-read`; core's own work passes the system context. A refusal is
      * thrown as `ContactRefusedError`, never answered as "no roles".
      */
     resolveUserRoles(ctx: ActorContext, username: string): Promise<string[]>;
@@ -114,7 +114,7 @@ declare class RoleManager extends BaseManager {
      * All or nothing (#2015): when any change cannot be made, the ones already
      * made are undone and a `RoleChangeError` is thrown, after it is logged as
      * an error and admins are notified. That includes a change that cannot even
-     * be attempted: no PersonManager, no Person record for the username, or no
+     * be attempted: no IdentityManager, no Person record for the username, or no
      * anchor Organization.
      */
     applyRoleDiff(username: string, oldRoles: string[], newRoles: string[]): Promise<void>;
@@ -139,9 +139,9 @@ declare class RoleManager extends BaseManager {
     grantToEveryAccountOnce(roleName: string, usernames: readonly string[], ctx: JobContext): Promise<number>;
     /**
      * Move every membership held by one Person `@id` to another (#1930): when
-     * PersonManager joins an account to an existing person, the roles the
+     * IdentityManager joins an account to an existing person, the roles the
      * account's person held go with the account. Returns how many records
-     * changed. PersonManager's join records the change. All or nothing (#2015).
+     * changed. IdentityManager's join records the change. All or nothing (#2015).
      */
     moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
     /**

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

@@ -132,6 +132,8 @@ export interface JobSubject {
     viaToken?: AgentTokenGrant;
     viaShare?: ShareGrant;
     viaProxy?: ProxyClaim;
+    /** #1999: the scheduled job a run acts as (`JobContext.job`). */
+    job?: string;
 }
 /**
  * User creation input data
@@ -343,9 +345,9 @@ declare class UserManager extends BaseManager {
     /**
      * Every account has exactly one identity record, made by `createUser`
      * (#2037). One that has none (written straight into the user store, or
-     * whose record was lost) gets it at boot, once, through PersonManager's
+     * whose record was lost) gets it at boot, once, through IdentityManager's
      * door under the system context, each creation recorded as
-     * `contact-manage`. The identity records are listed once and only the
+     * `identity-manage`. The identity records are listed once and only the
      * missing ones are made, so a large user store costs one read. A failure
      * is logged and the boot goes on: the role paths make the record when the
      * account is next used (`getByUserIdentifier`).
@@ -457,6 +459,16 @@ declare class UserManager extends BaseManager {
      * which accounts exist.
      */
     resetPasswordWithRecoveryWords(username: string, words: string, newPassword: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * A user's first password, chosen by themselves (#2049: after an
+     * invitation signed them in). Only for their own account, signed in as
+     * themselves (no token, share link or proxy), under `account-security`,
+     * and only while the account has no password: a password already set is
+     * changed on the profile, which asks for the current one. `false`,
+     * changing nothing, otherwise. The length rule is the route's, as for
+     * every password form. Recorded like any password change (`user-edit`).
+     */
+    setFirstPassword(username: string, newPassword: string, ctx: PermissionSubject): Promise<boolean>;
     /**
      * Change an account (#2025: one change at a time per account).
      *
@@ -529,10 +541,10 @@ declare class UserManager extends BaseManager {
         activeOnly?: boolean;
     }, ctx: ActorContext): Promise<Omit<User, 'password'>[]>;
     /**
-     * The account lifecycle reaches PersonManager's door under a system context
+     * The account lifecycle reaches IdentityManager's door under a system context
      * (#1930): keeping an account's person in step with the account is core's
      * own bookkeeping, not the caller's contact management, so it never depends
-     * on the caller holding `contact-manage`. The reason names the account and
+     * on the caller holding `identity-manage`. The reason names the account and
      * who changed it, so the record says why.
      */
     private personSyncContext;
@@ -547,7 +559,7 @@ declare class UserManager extends BaseManager {
     private syncPersonOnCreate;
     /**
      * At sign-up, offer the new account a person with no account who has the
-     * same email (#1930): PersonManager mails an "Is this you?" link, and joins
+     * same email (#1930): IdentityManager mails an "Is this you?" link, and joins
      * them only when the account confirms. Skipped when email is off. Never
      * fails the account write.
      */

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

@@ -1,5 +1,5 @@
 import { AttachmentMetadata, AttachmentProvider } from '../types/index.js';
-import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { ProviderInfo } from './BasePageProvider.js';
 import BaseProvider from './BaseProvider.js';
@@ -150,13 +150,7 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
      */
     getAttachmentByFilename(_filename: string): Promise<AttachmentMetadata | null>;
     /** Store a file in a store. The same bytes already in THAT store return the existing entry. */
-    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>;
     /** One file of a store, with its bytes; null when the store does not list it. */
     getFileInStore(_location: StoreFileLocation, _id: string): Promise<{
         entry: StoreFileEntry;

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

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

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

@@ -1,5 +1,5 @@
 import BaseAttachmentProvider, { FileInfo, User, AttachmentResult } from './BaseAttachmentProvider.js';
-import type { ProviderInfo, StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
+import type { ProviderInfo, StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import { AttachmentMetadata } from '../types/index.js';
 import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, AssetMetadata, AssetMetadataPatch } from '../types/Asset.js';
 import type { CreativeWork } from '../types/Schema.js';
@@ -213,6 +213,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     /**
      * Validate file against constraints
      * @param fileInfo - File information
+     * @param alsoAllowed - Types allowed beyond the site's list: only an import's kept original into its receiver's own vault (#2061)
      * @private
      */
     private validateFile;
@@ -261,13 +262,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     private requirePagesDirectory;
     private readStoreIndex;
     private writeStoreIndex;
-    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;

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

@@ -43,6 +43,10 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * derived, never stored.
      */
     constructor(engine: WikiEngine);
+    /** Each `<policy id> <retired name>` already warned about (#2038): said once per process. */
+    private readonly warnedRetired;
+    /** Warn, once per policy and name, that a policy names a retired permission and what it is read as (#2038). */
+    private warnRetiredOnce;
     /**
      * The policies in force right now, highest priority first.
      *
@@ -55,6 +59,14 @@ export declare class PolicyDecisionPoint extends BaseManager {
      *   not something to resolve silently here.
      */
     policies(): Policy[];
+    /**
+     * Whether a policy in force names the scheduled job `jobId` as a subject
+     * (`{ "type": "job", "value": jobId }`, #1999), allow or deny. When one
+     * does, the job's runs act as the job itself; when none does, as the system
+     * principal. Read live, so a site that removes the policy gives the job the
+     * system roles back at its next decision.
+     */
+    namesJob(jobId: string): boolean;
     /**
      * What each role permits: role name → the actions its holders are granted.
      *

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

@@ -178,7 +178,7 @@ declare class PolicyInformationPoint extends BaseManager {
      * resolves to the anonymous subject: the job then holds exactly what a
      * visitor holds, which is the safe answer for someone who no longer exists.
      */
-    resolveSubjectNow(username: string | undefined): Promise<UserContext>;
+    resolveSubjectNow(username: string | undefined, job?: string): Promise<UserContext>;
     /**
      * The subject as a page's own rules match it (#2022): for a job's subject
      * (`resolveRolesNow`, #1212), its username with the roles its account

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

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

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

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

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

@@ -70,7 +70,7 @@ export interface Person {
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
 /**
- * What a caller gives `PersonManager.create` (#1930): the person's fields.
+ * What a caller gives `IdentityManager.create` (#1930): the person's fields.
  * `identifier` is left out for a person with no account (one is generated);
  * UserManager passes the account's username when it creates the person for a
  * new account.

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

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

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

@@ -12,9 +12,9 @@
  * again because a `.d.ts` may not import a `.ts`. Four copies of one shape is
  * how a field gets added to one and missed in the others.
  */
-/** Who a policy grants to. `role` is the only type the evaluator matches today. */
+/** Who a policy grants to. The evaluator matches `role` and `job` (#1999), its `SUBJECT_MATCHERS`. */
 export interface PolicySubject {
-    /** `role`, and in future `user` or `group`. */
+    /** `role`, or `job` for a scheduled job acting as itself (#1999). */
     type: string;
     value: string;
 }

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

@@ -582,6 +582,27 @@ export interface StoreFileEntry {
     dateModified: string;
     /** Pages the file was uploaded onto. */
     mentions: string[];
+    /**
+     * An import's kept original (#2061): always served as a download
+     * (`Content-Disposition: attachment`, `nosniff`), never shown inline.
+     */
+    download?: true;
+}
+/** What `storeFileInStore` is told about a file it stores in a private store. */
+export interface StoreFileInput {
+    originalName: string;
+    mimeType: string;
+    description: string;
+    author?: string;
+    pageName?: string;
+    /**
+     * Set only by AttachmentManager for an import's keep into the receiver's
+     * own vault (#2061): `types` are allowed beyond the site's allow-list, and
+     * the file is marked {@link StoreFileEntry.download}.
+     */
+    keptOriginal?: {
+        types: readonly string[];
+    };
 }
 /**
  * A page in a private store (#1456): its entry in the store's OWN page index,

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

@@ -51,6 +51,11 @@
  * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
  * (paths inside its values included). An entry for any other key refuses the
  * addon, since it could unhide core's or another addon's secret.
+ *
+ * A fifth, `ngdpbase.access.policies` job subjects (#1999): an enabled addon's
+ * policy may name only its own scheduled jobs, `{ "type": "job", "value":
+ * "<slug>.<job>" }`. A policy naming core's job or another addon's refuses
+ * the addon, since it would grant that job permissions its owner never chose.
  */
 import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -119,6 +124,17 @@ export interface AddonSensitiveValuesLayer {
  * enabled addon's entries reach the merge, so only an enabled addon is checked.
  */
 export declare function addonSensitiveValuesLayer(addons: readonly AddonDefaults[]): AddonSensitiveValuesLayer;
+export interface AddonJobPolicyLayer {
+    /** Addons whose policies name a job that is not their own, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * Which jobs an addon's policies may name (#1999): its own, ids starting
+ * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
+ * reach the merge, so only an enabled addon is checked.
+ */
+export declare function addonJobPolicyLayer(addons: readonly AddonDefaults[]): AddonJobPolicyLayer;
 /** The configuration key that makes an addon site-critical (#1883). */
 export declare function addonSiteCriticalKey(slug: string): string;
 export interface AddonSiteCriticalLayer {

package/lib/src/utils/addonConfigLayer.js

@@ -51,6 +51,11 @@
  * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
  * (paths inside its values included). An entry for any other key refuses the
  * addon, since it could unhide core's or another addon's secret.
+ *
+ * A fifth, `ngdpbase.access.policies` job subjects (#1999): an enabled addon's
+ * policy may name only its own scheduled jobs, `{ "type": "job", "value":
+ * "<slug>.<job>" }`. A policy naming core's job or another addon's refuses
+ * the addon, since it would grant that job permissions its owner never chose.
  */
 import fs from 'fs';
 import path from 'path';
@@ -313,6 +318,37 @@ export function addonSensitiveValuesLayer(addons) {
     }
     return layer;
 }
+/**
+ * Which jobs an addon's policies may name (#1999): its own, ids starting
+ * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
+ * reach the merge, so only an enabled addon is checked.
+ */
+export function addonJobPolicyLayer(addons) {
+    const layer = { refused: new Map(), problems: [] };
+    for (const addon of addons) {
+        if (!addon.enabled)
+            continue;
+        const policies = addon.defaults['ngdpbase.access.policies'];
+        if (!Array.isArray(policies))
+            continue;
+        const foreign = [];
+        for (const policy of policies) {
+            const subjects = isPlainObject(policy) && Array.isArray(policy.subjects) ? policy.subjects : [];
+            for (const subject of subjects) {
+                if (!isPlainObject(subject) || subject.type !== 'job')
+                    continue;
+                if (typeof subject.value !== 'string' || !subject.value.startsWith(`${addon.slug}.`))
+                    foreign.push(`'${String(subject.value)}' (policy '${String(policy.id)}')`);
+            }
+        }
+        if (foreign.length === 0)
+            continue;
+        const reason = `its policies name the job(s) ${foreign.join(', ')}, which are not its own; an add-on's policy names only its own jobs, ${addon.slug}.<job>`;
+        layer.refused.set(addon.slug, reason);
+        layer.problems.push(`${addonProblemSubject(addon.slug, addon.enabled)}: ${reason}; the add-on is not loaded`);
+    }
+    return layer;
+}
 /** The configuration key that makes an addon site-critical (#1883). */
 export function addonSiteCriticalKey(slug) {
     return `ngdpbase.addons.${slug}.site-critical`;
@@ -402,9 +438,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const databaseLayer = addonDatabaseLayer(addons, custom);
     const criticalLayer = addonSiteCriticalLayer(addons, custom);
     const sensitiveLayer = addonSensitiveValuesLayer(addons);
+    const jobPolicyLayer = addonJobPolicyLayer(addons);
     const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused])
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused, ...jobPolicyLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -418,14 +455,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,

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

@@ -18,9 +18,11 @@
  * - `registerShim` and `registerReceiver` (#1979, ICE) register into the import
  *   engine under this add-on's slug, and only the names its manifest declares;
  * - the egress tools (`resolveEgressPolicy`, `validateUrl`,
- *   `createGuardedElasticsearchClient`, `refusedNodeMessage`) and `isAtLeast`
- *   are core's own pure functions, handed on unchanged, so an add-on never
- *   imports them from `dist/` (#1813);
+ *   `createGuardedElasticsearchClient`, `refusedNodeMessage`), `isAtLeast`
+ *   and `zonedParts` (#1998) are core's own pure functions, handed on
+ *   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);
  * - 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.
@@ -36,6 +38,8 @@ import { resolveEgressPolicy } from '../http/egressPolicy.js';
 import { validateUrl } from '../http/ssrf.js';
 import { createGuardedElasticsearchClient, refusedNodeMessage } from '../http/guardedElasticsearch.js';
 import { isAtLeast } from './version.js';
+import { zonedParts } from './availability.js';
+import { KeyedSerial } from './keyedSerial.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import type { IceReceiver, IceShim } from '../ice/types.js';
@@ -80,6 +84,20 @@ export interface AddonHost {
     readonly refusedNodeMessage: typeof refusedNodeMessage;
     /** Whether an `x.y.z` version is at least another; throws on a version that is not `x.y.z`. */
     readonly isAtLeast: typeof isAtLeast;
+    /**
+     * #1998: an instant in a named time zone, as its local parts: `year`,
+     * `month` (1–12), `date` (`YYYY-MM-DD`), `day` (weekday name) and `minutes`
+     * since midnight. A scheduled job passes its `ctx.slot` and
+     * `BackgroundJobManager.scheduleTimeZone()` to learn which local month or
+     * day the slot falls in. An unknown zone answers in UTC.
+     */
+    readonly zonedParts: typeof zonedParts;
+    /**
+     * #2065: a new `KeyedSerial` (core's own) at each call; take one per manager.
+     * Run each read-modify-write of one of your records inside `run(recordId, fn)`,
+     * the read included. Not re-entrant: `fn` must not `run` the same key again.
+     */
+    readonly keyedSerial: () => KeyedSerial;
     /**
      * #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.