@jwilleke/ngdpbase-types 5.30.0 → 5.31.0

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,16 +37,16 @@ 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 AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';
-export type { default as IdentityManager, LinkOfferOutcome } from '../../src/managers/IdentityManager.js';
+export type { default as IdentityManager, LinkOfferOutcome, AffiliationQuery, IdentitySearch, IdentityMatch } from '../../src/managers/IdentityManager.js';
 export type { 
 /** @deprecated Renamed `IdentityManager` (#2038); this alias goes after one release. */
 default as PersonManager } from '../../src/managers/IdentityManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
-export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
+export type { Person, PersonAffiliation, LegacyPersonAffiliation, PersonChange, PersonInput, PersonUpdate } from '../../src/types/Person.js';
 export type { Organization, OrganizationInput, OrganizationUpdate, ContactPoint, ContactPointEntry, PostalAddress } from '../../src/types/Organization.js';
 export type { ContactRefusedError } from '../../src/utils/contactAccess.js';
 export type { default as RoleManager } from '../../src/managers/RoleManager.js';

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

@@ -71,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 {

package/lib/src/context/JobContext.js

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

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

@@ -1,8 +1,31 @@
 import BaseManager, { type BackupFolder, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Person, PersonInput, PersonUpdate } from '../types/Person.js';
+import type { Person, PersonAffiliation, PersonChange, PersonInput } from '../types/Person.js';
 import type { PersonProvider } from '../types/PersonProvider.js';
 import { type ActorContext } from '../context/ActorContext.js';
+/** What `search(ctx, { affiliation })` looks for (#2039). */
+export interface AffiliationQuery {
+    /** The organization, by its `@id` (or `{ '@id' }`). */
+    memberOf: string | {
+        '@id': string;
+    };
+    /** The title, compared without case or surrounding spaces. Left out: any title, or none. */
+    title?: string;
+    /** True (the default): only affiliations held today, the first and last day included. False: any, past or future too. */
+    current?: boolean;
+}
+/** A search by affiliation (#2039). `limit` as for a text search; 0 is no limit. */
+export interface IdentitySearch {
+    affiliation: AffiliationQuery;
+    limit?: number;
+}
+/** One identity a search by affiliation found: a user or a contact, and the affiliations that matched. */
+export interface IdentityMatch {
+    identity: Person;
+    /** True for a user (an identity with credentials), false for a contact. */
+    hasCredentials: boolean;
+    affiliations: PersonAffiliation[];
+}
 /** What the confirmation page shows: the person the link would join. */
 export interface LinkOfferDetails {
     personName: string | null;
@@ -52,6 +75,7 @@ declare class IdentityManager extends BaseManager {
     private storageDir;
     private byIdentifierCache;
     private byIdCache;
+    private allCache;
     private metricsRef;
     /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
     private linkOffers;
@@ -59,6 +83,18 @@ declare class IdentityManager extends BaseManager {
     private readonly accountRecords;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Once, at start-up (#2039): every identity record still holding an
+     * affiliation in the old `{ organization, role? }` shape is rewritten as
+     * schema.org `OrganizationRole` (organization → `memberOf`, role →
+     * `roleName`), each rewrite recorded as `identity-manage` (`person-update`,
+     * field `affiliation`) under the system context. Nothing is dropped: any
+     * other field an old entry carries is kept on it. A record with no old entry
+     * is not touched, so a second start finds nothing to do. A record that
+     * cannot be rewritten is logged and left as it is; reads convert it anyway.
+     * Runs before any request, so nothing else writes these records meanwhile.
+     */
+    private convertLegacyAffiliations;
     /** `ngdpbase.application.persons.storagedir`, resolved: where the records are. */
     private configuredStorageDir;
     /**
@@ -79,6 +115,8 @@ declare class IdentityManager extends BaseManager {
      */
     getByIdentifier(ctx: ActorContext, identifier: string): Promise<Person | null>;
     private cachedById;
+    /** Every record, affiliations in the current shape, read from the provider once per write (#2039). */
+    private allRecords;
     private cachedByIdentifier;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
@@ -93,11 +131,20 @@ declare class IdentityManager extends BaseManager {
      * `query`, ignoring case; an empty query matches everyone. `accountless`
      * narrows to persons with no account. At most `limit` results
      * (`ngdpbase.application.persons.search.limit` by default).
+     *
+     * Or by affiliation (#2039): `search(ctx, { affiliation: { memberOf, title?,
+     * current? } })` finds every identity, users and contacts alike, with an
+     * affiliation to that organization: with that title when one is given, and
+     * held today (the first and last day included) unless `current` is false.
+     * Each match says whether it has credentials and which affiliations matched.
+     * Checked like any read of others' records: `identity-read`.
      */
     search(ctx: ActorContext, query: string, options?: {
         limit?: number;
         accountless?: boolean;
     }): Promise<Person[]>;
+    search(ctx: ActorContext, query: IdentitySearch): Promise<IdentityMatch[]>;
+    private searchByAffiliation;
     /**
      * Create a person. With no `identifier` the person has no account and gets
      * `person:<uuid>`. An `identifier` must be an existing account that has no
@@ -108,8 +155,13 @@ declare class IdentityManager extends BaseManager {
      * Change a person's fields, affiliations included. `@id` and `identifier`
      * never change here. The caller's own identity record under
      * `profile-manage`, anyone else's under `identity-manage` (#2018).
+     *
+     * Affiliations (#2039): one with the site's own organization is a fact, so
+     * adding, changing or removing one also asks `identity-manage`, even on the
+     * caller's own record; one with any other organization is a claim, which a
+     * user may set on their own record under `profile-manage`.
      */
-    update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
+    update(ctx: ActorContext, id: string, patch: PersonChange): Promise<Person | null>;
     delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
      * An administrator joins a person who has no account to an account (#1930),
@@ -150,10 +202,18 @@ declare class IdentityManager extends BaseManager {
      */
     private join;
     /**
-     * Each affiliation names an organization that exists, looked up with the
-     * caller's context; `role` is trimmed text. Throws on any other shape.
+     * Each affiliation is a schema.org `OrganizationRole` (#2039): `memberOf` an
+     * organization that exists, an optional `roleName` (the title, trimmed free
+     * text) and optional `startDate` / `endDate` (`YYYY-MM-DD`, the start not
+     * after the end; a null end is an ongoing one, stored without it). An entry
+     * in the old `{ organization, role? }` shape is converted (one release, for
+     * add-ons not yet switched). Throws on any other shape. The organization is
+     * looked up as core's own check, under the system context, so a user may
+     * name one on their own record without `identity-read`.
      */
     private checkedAffiliations;
+    /** The site's own organization's `@id` (`OrganizationManager.getInstallOrg`): an affiliation with it is a fact (#2039). */
+    private siteOrganizationId;
     private configNumber;
     /**
      * Clear all caches. Called on every write — the simplest correct

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

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

package/lib/src/managers/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/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
@@ -220,6 +222,8 @@ declare class UserManager extends BaseManager {
     private passwordSalt?;
     /** One read-merge-write at a time per account, keyed by the normalized username (#2025). */
     private readonly accountWrites;
+    /** Whether this process has already reported the withheld session cookie (#2071). */
+    private sessionCookieWithheldReported;
     /**
      * Creates a new UserManager instance
      *
@@ -253,6 +257,15 @@ declare class UserManager extends BaseManager {
      * its safe message and other routes their own.
      */
     private assertEmailFree;
+    /**
+     * The session cookie is `secure` and a request came over plain http, so
+     * express-session sent no cookie and nobody can sign in (#2071). Sessions
+     * are this manager's, so the report is too: an error in the log, the
+     * dashboard's "needs your attention", and a notification for admins, once
+     * per process. Every later call is one boolean check, because app.ts calls
+     * this on each such request.
+     */
+    reportSessionCookieWithheld(): void;
     /**
      * 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

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/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

@@ -59,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