@jwilleke/ngdpbase-types 5.29.1 → 5.30.1

package/lib/src/utils/addonHost.js

@@ -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.
@@ -35,6 +37,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 { auditDeclarationsFrom } from './auditRegistry.js';
@@ -117,6 +121,8 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         validateUrl,
         createGuardedElasticsearchClient,
         refusedNodeMessage,
-        isAtLeast
+        isAtLeast,
+        zonedParts,
+        keyedSerial: () => new KeyedSerial()
     });
 }

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

@@ -54,10 +54,18 @@ export declare const AUDIT_EVENT: {
     readonly CONSENT_GRANT: "consent-grant";
     /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     readonly CONSENT_WITHDRAW: "consent-withdraw";
-    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
-    readonly CONTACT_MANAGE: "contact-manage";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
+    /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    readonly IDENTITY_MANAGE: "identity-manage";
+    /** Invitation cancelled (#2049): an administrator cancelled it or sent a new one, the email could not be sent, or the account was deleted; the link stops working */
+    readonly INVITATION_CANCEL: "invitation-cancel";
+    /** Invitation expired (#2049): the link was not used in time and was removed */
+    readonly INVITATION_EXPIRE: "invitation-expire";
+    /** Invitation sent (#2049): a one-time link emailed to a new user to set up their sign-in; user is who sent it, resource the account invited. A credential nobody knows exists is the worst case, so it is recorded before the link exists */
+    readonly INVITATION_SEND: "invitation-send";
+    /** Invitation used (#2049): the invited user opened their link and was signed in once; the link is spent */
+    readonly INVITATION_USE: "invitation-use";
     /** A background job finished successfully */
     readonly JOB_COMPLETED: "job-completed";
     /** A background job failed */

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

@@ -61,10 +61,18 @@ export const AUDIT_EVENT = {
     CONSENT_GRANT: 'consent-grant',
     /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     CONSENT_WITHDRAW: 'consent-withdraw',
-    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
-    CONTACT_MANAGE: 'contact-manage',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
+    /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    IDENTITY_MANAGE: 'identity-manage',
+    /** Invitation cancelled (#2049): an administrator cancelled it or sent a new one, the email could not be sent, or the account was deleted; the link stops working */
+    INVITATION_CANCEL: 'invitation-cancel',
+    /** Invitation expired (#2049): the link was not used in time and was removed */
+    INVITATION_EXPIRE: 'invitation-expire',
+    /** Invitation sent (#2049): a one-time link emailed to a new user to set up their sign-in; user is who sent it, resource the account invited. A credential nobody knows exists is the worst case, so it is recorded before the link exists */
+    INVITATION_SEND: 'invitation-send',
+    /** Invitation used (#2049): the invited user opened their link and was signed in once; the link is spent */
+    INVITATION_USE: 'invitation-use',
     /** A background job finished successfully */
     JOB_COMPLETED: 'job-completed',
     /** A background job failed */

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

@@ -139,13 +139,26 @@ export interface TokenInput extends CommonInput {
     /** Only meaningful for `revoke`; ignored otherwise. */
     revokedBy?: string;
 }
-export interface AttachmentInput extends CommonInput {
-    op: AttachmentOp;
+/**
+ * What an attachment record says about the file. A file in an ENCRYPTED store
+ * is recorded by its id and the store only (#2048): its name, its page and its
+ * size are the store's to keep sealed, so the record carries none of them.
+ */
+export type AttachmentDetail = {
     attachmentId: string;
     filename: string;
     pageName?: string | null;
     sizeBytes?: number | null;
-}
+} | {
+    attachmentId: string;
+    sealedStore: {
+        owner: string;
+        store: string;
+    };
+};
+export type AttachmentInput = CommonInput & {
+    op: AttachmentOp;
+} & AttachmentDetail;
 /**
  * Build the audit event for a page create, edit, rename, or link rewrite.
  *

package/lib/src/utils/auditEvents.js

@@ -145,18 +145,17 @@ export function buildPageViewAuditEvent(input) {
  * unattended destruction is the case someone reviewing the log is looking for.
  */
 export function buildAttachmentAuditEvent(input) {
-    const { op, attachmentId, filename, pageName, sizeBytes, viaToken } = input;
+    const { op, attachmentId, viaToken } = input;
     const who = whoOf(input);
-    const metadata = {
-        attachmentId,
-        filename,
-        ...tokenMetadata(viaToken),
-        ...who.metadata
-    };
-    if (pageName)
-        metadata.pageName = pageName;
-    if (typeof sizeBytes === 'number')
-        metadata.sizeBytes = sizeBytes;
+    const metadata = 'sealedStore' in input
+        ? { attachmentId, owner: input.sealedStore.owner, store: input.sealedStore.store, sealed: true, ...tokenMetadata(viaToken), ...who.metadata }
+        : { attachmentId, filename: input.filename, ...tokenMetadata(viaToken), ...who.metadata };
+    if (!('sealedStore' in input)) {
+        if (input.pageName)
+            metadata.pageName = input.pageName;
+        if (typeof input.sizeBytes === 'number')
+            metadata.sizeBytes = input.sizeBytes;
+    }
     const severity = op === 'delete'
         ? (viaToken ? 'high' : 'medium')
         : (viaToken ? 'medium' : 'low');

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

@@ -0,0 +1,120 @@
+/**
+ * Is the instance open to ordinary traffic, and if not, why (#1432)?
+ *
+ * "Is the site open" is not "may this identity do this". The second is the
+ * permission door; this is the first, and it has several reasons — maintenance,
+ * a schedule such as business hours, and a holiday. They shared one property:
+ * the configuration shipped switches for all of them and only maintenance was
+ * ever enforced, so an operator could turn business hours on and nothing
+ * happened. `PolicyInformationPoint` carried the unreachable implementations
+ * (`checkBusinessHours`, `checkHolidayRestrictions`, `checkEnhancedTimeRestrictions`),
+ * which is also the wrong manager for the question.
+ *
+ * One resolver, one gate, one dialog, different messages. This returns the
+ * FIRST reason that closes the instance, with the operator's own wording for
+ * it, and the gate middleware renders it.
+ *
+ * Read per request, never cached at boot, so an admin toggle takes effect
+ * without a restart. Maintenance itself is `MaintenanceState`'s (#1906): the
+ * gate passes its visitor view in, and this only ranks it first.
+ */
+import type { MaintenanceVisitorView } from './maintenanceState.js';
+/**
+ * Read one configuration value. No fallback parameter, deliberately.
+ *
+ * A fallback in the call is a second place the value can come from, and it is
+ * invisible to the operator: the shipped `config/app-default-config.json` can
+ * lose a key and nothing says so, because the caller quietly supplied one.
+ * Every key this module reads IS declared there, so absence means a broken
+ * configuration, not a value to invent.
+ *
+ * What this module does with an absent value:
+ *
+ * - __a switch__ (`…enabled`) reads as OFF, and says so in the log. A missing
+ *   switch must never CLOSE the instance — that would lock everyone out over a
+ *   typo — but it is still reported rather than assumed.
+ * - __a window, schedule or holiday map__ absent means nothing to enforce.
+ * - __a message__ falls back to a constant, because something has to render on
+ *   the page. That is the only fallback here, and it is display text.
+ */
+export type ReadProperty = (key: string) => unknown;
+/** Which reason closed the instance. */
+export type AvailabilityKind = 'maintenance' | 'schedule' | 'holiday' | 'misconfigured';
+export interface AvailabilityState {
+    /** Whether ordinary traffic is refused. */
+    blocked: boolean;
+    /** Which reason closed it; null when open. */
+    kind: AvailabilityKind | null;
+    /** Shown on the page. Never empty when blocked. */
+    message: string;
+    /** Whether an administrator may still reach the instance. */
+    allowAdmins: boolean;
+    /** Operator-supplied estimate, maintenance only. */
+    estimatedDuration: string | null;
+}
+export declare const BUSINESS_HOURS_ENABLED_KEY = "ngdpbase.access-control.business-hours.enabled";
+export declare const BUSINESS_HOURS_MESSAGE_KEY = "ngdpbase.access-control.business-hours.message";
+export declare const CUSTOM_SCHEDULES_ENABLED_KEY = "ngdpbase.access-control.custom-schedules.enabled";
+export declare const CUSTOM_SCHEDULES_FILE_KEY = "ngdpbase.access-control.custom-schedules.schedules";
+export declare const SCHEDULES_KEY = "ngdpbase.schedules";
+export declare const HOLIDAYS_ENABLED_KEY = "ngdpbase.holidays.enabled";
+export declare const HOLIDAYS_DATES_KEY = "ngdpbase.holidays.dates";
+export declare const HOLIDAYS_MESSAGE_KEY = "ngdpbase.holidays.message";
+export declare const TIME_ZONE_KEY = "ngdpbase.time-zone";
+/** A named schedule from `ngdpbase.schedules`. */
+export interface ScheduleRule {
+    days?: string[];
+    startTime?: string;
+    endTime?: string;
+    /** `allow` opens the window; `deny` closes it. Absent reads as `allow`. */
+    type?: string;
+}
+export interface Schedule {
+    name?: string;
+    description?: string;
+    timeZone?: string;
+    rules?: ScheduleRule[];
+    exceptions?: string[];
+    enabled?: boolean;
+    message?: string;
+}
+/** A holiday entry. The key carries the date — `2026-07-04` or `*-12-25`. */
+export interface HolidayEntry {
+    name?: string;
+    message?: string;
+    enabled?: boolean;
+}
+/**
+ * The instant, in a named time zone, as the parts a schedule compares:
+ * the weekday and minutes since midnight, plus the ISO date for a holiday,
+ * and the local year and month (1–12), which a month boundary needs (#1998).
+ * An add-on reaches it as `host.zonedParts`.
+ *
+ * Uses `Intl` rather than arithmetic on the epoch so daylight saving is the
+ * platform's problem, not ours.
+ */
+export declare function zonedParts(now: Date, timeZone: string): {
+    day: string;
+    minutes: number;
+    date: string;
+    year: number;
+    month: number;
+};
+/**
+ * Whether a schedule is open at `now`.
+ *
+ * A `deny` rule matching the day closes it outright. Otherwise an `allow` rule
+ * must match both the day and the time window. A schedule with no rules is
+ * open — an empty schedule is not a lockout.
+ */
+export declare function scheduleIsOpen(schedule: Schedule, now: Date, fallbackZone: string): boolean;
+/** Whether `date` (ISO `YYYY-MM-DD`) matches a holiday key, including `*-MM-DD`. */
+export declare function holidayKeyMatches(key: string, date: string): boolean;
+/**
+ * The first reason the instance is closed, or an open state.
+ *
+ * Order is maintenance, then schedule, then holiday: the operator's own switch
+ * before anything time-based, so "I closed it" is never reported as "it is a
+ * holiday".
+ */
+export declare function resolveAvailability(get: ReadProperty, now?: Date, maintenance?: MaintenanceVisitorView | null): AvailabilityState;

package/lib/src/utils/availability.js

@@ -0,0 +1,174 @@
+'use strict';
+export const BUSINESS_HOURS_ENABLED_KEY = 'ngdpbase.access-control.business-hours.enabled';
+export const BUSINESS_HOURS_MESSAGE_KEY = 'ngdpbase.access-control.business-hours.message';
+export const CUSTOM_SCHEDULES_ENABLED_KEY = 'ngdpbase.access-control.custom-schedules.enabled';
+export const CUSTOM_SCHEDULES_FILE_KEY = 'ngdpbase.access-control.custom-schedules.schedules';
+export const SCHEDULES_KEY = 'ngdpbase.schedules';
+export const HOLIDAYS_ENABLED_KEY = 'ngdpbase.holidays.enabled';
+export const HOLIDAYS_DATES_KEY = 'ngdpbase.holidays.dates';
+export const HOLIDAYS_MESSAGE_KEY = 'ngdpbase.holidays.message';
+export const TIME_ZONE_KEY = 'ngdpbase.time-zone';
+const DEFAULT_SCHEDULE_MESSAGE = 'The site is closed at this time. Please try again during opening hours.';
+const DEFAULT_HOLIDAY_MESSAGE = 'The site is closed for a holiday. Please try again later.';
+function toBoolean(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true')
+            return true;
+        if (normalized === 'false')
+            return false;
+        return fallback;
+    }
+    if (typeof value === 'number')
+        return value !== 0;
+    return fallback;
+}
+function text(value, fallback) {
+    return typeof value === 'string' && value.trim() !== '' ? value : fallback;
+}
+/**
+ * The instant, in a named time zone, as the parts a schedule compares:
+ * the weekday and minutes since midnight, plus the ISO date for a holiday,
+ * and the local year and month (1–12), which a month boundary needs (#1998).
+ * An add-on reaches it as `host.zonedParts`.
+ *
+ * Uses `Intl` rather than arithmetic on the epoch so daylight saving is the
+ * platform's problem, not ours.
+ */
+export function zonedParts(now, timeZone) {
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hour12: false,
+            weekday: 'long',
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit'
+        }).formatToParts(now);
+    }
+    catch {
+        // An unknown zone must not decide the site is closed: fall back to UTC.
+        return zonedParts(now, 'UTC');
+    }
+    const find = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    const hour = Number(find('hour'));
+    return {
+        day: find('weekday').toLowerCase(),
+        // Intl renders midnight as 24 in some locales with hour12:false.
+        minutes: (hour === 24 ? 0 : hour) * 60 + Number(find('minute')),
+        date: `${find('year')}-${find('month')}-${find('day')}`,
+        year: Number(find('year')),
+        month: Number(find('month'))
+    };
+}
+function minutesOf(hhmm) {
+    if (typeof hhmm !== 'string')
+        return null;
+    const match = /^(\d{1,2}):(\d{2})$/.exec(hhmm.trim());
+    if (!match)
+        return null;
+    const hours = Number(match[1]);
+    const mins = Number(match[2]);
+    if (hours > 23 || mins > 59)
+        return null;
+    return hours * 60 + mins;
+}
+/**
+ * Whether a schedule is open at `now`.
+ *
+ * A `deny` rule matching the day closes it outright. Otherwise an `allow` rule
+ * must match both the day and the time window. A schedule with no rules is
+ * open — an empty schedule is not a lockout.
+ */
+export function scheduleIsOpen(schedule, now, fallbackZone) {
+    const rules = Array.isArray(schedule.rules) ? schedule.rules : [];
+    if (rules.length === 0)
+        return true;
+    const { day, minutes } = zonedParts(now, text(schedule.timeZone, fallbackZone));
+    const matchesDay = (rule) => {
+        if (!Array.isArray(rule.days) || rule.days.length === 0)
+            return true;
+        return rule.days.some((d) => typeof d === 'string' && d.trim().toLowerCase() === day);
+    };
+    for (const rule of rules) {
+        if (rule.type === 'deny' && matchesDay(rule))
+            return false;
+    }
+    let sawAllow = false;
+    for (const rule of rules) {
+        if (rule.type === 'deny')
+            continue;
+        sawAllow = true;
+        if (!matchesDay(rule))
+            continue;
+        const start = minutesOf(rule.startTime);
+        const end = minutesOf(rule.endTime);
+        if (start === null || end === null)
+            return true; // a malformed window does not close the site
+        if (start <= end ? minutes >= start && minutes < end : minutes >= start || minutes < end)
+            return true;
+    }
+    return !sawAllow;
+}
+/** Whether `date` (ISO `YYYY-MM-DD`) matches a holiday key, including `*-MM-DD`. */
+export function holidayKeyMatches(key, date) {
+    if (key === date)
+        return true;
+    if (key.startsWith('*-'))
+        return date.slice(5) === key.slice(2);
+    return false;
+}
+/**
+ * The first reason the instance is closed, or an open state.
+ *
+ * Order is maintenance, then schedule, then holiday: the operator's own switch
+ * before anything time-based, so "I closed it" is never reported as "it is a
+ * holiday".
+ */
+export function resolveAvailability(get, now = new Date(), maintenance = null) {
+    // #1906: `engine.maintenance.visitorView(…)`, null when the site is not in
+    // maintenance mode. Its message is already the one visitors may see.
+    if (maintenance) {
+        return {
+            blocked: true,
+            kind: 'maintenance',
+            message: maintenance.message,
+            allowAdmins: maintenance.adminsMayEnter,
+            estimatedDuration: maintenance.estimatedDuration
+        };
+    }
+    const open = {
+        blocked: false, kind: null, message: '', allowAdmins: true, estimatedDuration: null
+    };
+    const fallbackZone = text(get(TIME_ZONE_KEY), 'UTC');
+    // An administrator can always reach a time-closed instance: a schedule that
+    // locks out the only person who can change it is a trap, and unlike
+    // maintenance there is no switch to flip from outside.
+    const closed = (kind, message) => ({
+        blocked: true, kind, message, allowAdmins: true, estimatedDuration: null
+    });
+    const schedules = (get(SCHEDULES_KEY) ?? {});
+    if (toBoolean(get(BUSINESS_HOURS_ENABLED_KEY), false)) {
+        const schedule = schedules['business-hours'];
+        if (schedule && toBoolean(schedule.enabled, true) && !scheduleIsOpen(schedule, now, fallbackZone)) {
+            return closed('schedule', text(schedule.message ?? get(BUSINESS_HOURS_MESSAGE_KEY), DEFAULT_SCHEDULE_MESSAGE));
+        }
+    }
+    if (toBoolean(get(HOLIDAYS_ENABLED_KEY), false)) {
+        const dates = (get(HOLIDAYS_DATES_KEY) ?? {});
+        const { date } = zonedParts(now, fallbackZone);
+        for (const [key, entry] of Object.entries(dates)) {
+            if (!entry || !toBoolean(entry.enabled, true))
+                continue;
+            if (!holidayKeyMatches(key, date))
+                continue;
+            return closed('holiday', text(entry.message ?? get(HOLIDAYS_MESSAGE_KEY), DEFAULT_HOLIDAY_MESSAGE));
+        }
+    }
+    return open;
+}

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

@@ -1,11 +1,11 @@
 /**
  * The contacts door's one decision and its one record (#1930).
  *
- * PersonManager and OrganizationManager are the enforcement points for
+ * IdentityManager and OrganizationManager are the enforcement points for
  * contacts. Both ask the PDP the same two questions with the caller's
- * context: `contact-read` to list, search or view, `contact-manage` to
+ * context: `identity-read` to list, search or view, `identity-manage` to
  * create, change, delete or link; and both record each change as the
- * `contact-manage` audit event. That rule lives here once, so the two doors
+ * `identity-manage` audit event. That rule lives here once, so the two doors
  * cannot drift (operator, 2026-10-20).
  *
  * A refusal is thrown as {@link ContactRefusedError}, carrying the decision.
@@ -15,7 +15,7 @@
  *
  * Every lookup takes a context too (#2018, operator 2026-10-23), through
  * {@link requireRecordAccess}: a user's own identity record under
- * `profile-manage`, anyone else's under `contact-read` / `contact-manage`, and
+ * `profile-manage`, anyone else's under `identity-read` / `identity-manage`, and
  * core's own reads under the system context without a policy evaluation, so
  * resolving roles on every request stays cheap.
  */
@@ -27,8 +27,8 @@ type EngineLike = {
 };
 /** What a contacts door asks: `read` to list, search or view; `manage` to change. */
 export declare const CONTACT_PERMISSION: {
-    readonly read: "contact-read";
-    readonly manage: "contact-manage";
+    readonly read: "identity-read";
+    readonly manage: "identity-manage";
 };
 /** A contacts door said no. `permission` is what was refused; `decision` is the PDP's answer. */
 export declare class ContactRefusedError extends Error {
@@ -38,7 +38,7 @@ export declare class ContactRefusedError extends Error {
 }
 /**
  * Throws {@link ContactRefusedError} unless `ctx` may do `kind` (`read` asks
- * `contact-read`, `manage` asks `contact-manage`), and each of `also` (a link
+ * `identity-read`, `manage` asks `identity-manage`), and each of `also` (a link
  * to an account also asks `user-edit`). A missing context or decision point
  * refuses: closed, never open.
  */
@@ -58,7 +58,7 @@ export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | nul
  * - read it as core's own work ({@link isSystemWork}): allowed, not evaluated;
  * - read or change its own identity record (the context's username is the
  *   record's `identifier`): `profile-manage`, which every user holds;
- * - read or change any other record: `contact-read` / `contact-manage`.
+ * - read or change any other record: `identity-read` / `identity-manage`.
  *
  * `record` is the identity record (or what names it, `{ identifier }`); left
  * out for a record that is never anyone's own (an organization, a role).
@@ -86,7 +86,7 @@ export interface ContactChange {
     via?: 'admin' | 'email';
 }
 /**
- * Record a contacts change as `contact-manage`, under the caller's context.
+ * Record a contacts change as `identity-manage`, under the caller's context.
  * `continue`: a lost record is counted, the change stands. A system context
  * goes through `recordSystemAction`, so the bootstrap admin's person, made
  * before the audit sink is up, is recorded once it is.

package/lib/src/utils/keyedSerial.js

@@ -0,0 +1,41 @@
+/**
+ * KeyedSerial — one task at a time per key, within this process (#2015).
+ *
+ * A read-modify-write of one record (read the file, change it, write it back)
+ * is only safe while nothing else writes that record in between. Two role
+ * changes to one role used to interleave: each read the member list before the
+ * other wrote it, and the second write dropped the first one's member. Running
+ * every read-modify-write of a key through `run` makes them happen one after
+ * another, each reading what the last one wrote. Different keys still run side
+ * by side.
+ *
+ * What it does not do:
+ *
+ * - **Not across processes.** Two server processes sharing one data folder can
+ *   still race; no supported deployment runs that way.
+ * - **Not re-entrant.** A task must not `run` the same key again and wait for
+ *   it: the inner task queues behind the outer one, which never finishes.
+ *
+ * A failed task fails its own caller only; the next task on the key runs as
+ * usual. A key's entry is dropped once its queue is empty, so the map holds
+ * only keys with work in flight.
+ */
+export class KeyedSerial {
+    /** The settled tail of each key's queue: never rejects. */
+    tails = new Map();
+    /** Run `task` after every earlier task on `key` has settled; resolves or rejects as `task` does. */
+    run(key, task) {
+        const before = this.tails.get(key) ?? Promise.resolve();
+        const result = before.then(task);
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(key, tail);
+        void tail.then(() => { if (this.tails.get(key) === tail)
+            this.tails.delete(key); });
+        return result;
+    }
+    /** Resolves once every task queued so far, on every key, has settled (shutdown). */
+    async settled() {
+        await Promise.all([...this.tails.values()]);
+    }
+}
+export default KeyedSerial;

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

@@ -14,7 +14,7 @@
  */
 import { type PrivateStoreLayout } from './privateStorePath.js';
 import { type UserCatalog } from './privateStoreCatalogs.js';
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import type { LinkPublicKey, Lockbox } from './shareLockbox.js';
 export declare function unlockPrivateStores(sessionId: string, username: string, kek: Buffer): void;
 export declare function getSessionUserIndex(sessionId: string): UserCatalog | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.29.1",
+  "version": "5.30.1",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",