@jwilleke/ngdpbase-types 5.30.1 → 5.32.0

package/lib/src/providers/databaseMigrations.js

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

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

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

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

@@ -39,7 +39,10 @@ export interface ContactPoint {
     /** Who or what this contact point reaches, e.g. an agent's or an emergency contact's name (schema.org Thing.name). */
     name?: string;
     email?: string;
+    /** E.164 (`+14155552671`) when written from /profile (#2073); add-ons may store other forms. */
     telephone?: string;
+    /** A phone's extension, digits, kept apart from `telephone` (#2073). */
+    extension?: string;
     url?: string;
     availableLanguage?: string[];
 }

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

@@ -17,15 +17,40 @@
  */
 import type { PostalAddress, ContactPointEntry } from './Organization.js';
 /**
- * One organization a person is affiliated with (#1930): schema.org
- * `affiliation`, with the person's role or title there when one is known.
+ * One affiliation of a digital identity (#2039): schema.org `affiliation`
+ * with an `OrganizationRole`, as the identity model says
+ * (`docs/planning/identity-model.md`, "Affiliation shape"). It puts the
+ * identity in a group, the organization plus the title, and never grants a
+ * permission.
+ *
  * The organization is named by its `@id`; OrganizationManager lists an
  * organization's people by reading these, so the link is stored once, here.
+ * With the site's own organization it is a fact, set only under
+ * `identity-manage`; with any other it is a claim, which a user may also set
+ * on their own identity record. IdentityManager's door decides.
  */
 export interface PersonAffiliation {
-    /** The organization's `@id`. */
+    '@type': 'OrganizationRole';
+    /** The organization, by its `@id`. */
+    memberOf: {
+        '@id': string;
+    };
+    /** The affiliation's title there (Owner, Treasurer, Vendor): free text, never a Role. Left out when none is known. */
+    roleName?: string;
+    /** ISO date (`YYYY-MM-DD`) the affiliation began; left out when not known. */
+    startDate?: string;
+    /** ISO date (`YYYY-MM-DD`) it ended or ends, the day included; left out while it is ongoing. */
+    endDate?: string;
+}
+/**
+ * An affiliation in its shape before #2039, `{ organization, role? }`.
+ * Converted (organization → `memberOf`, role → `roleName`) when read, once on
+ * disk at start-up, and when an add-on still writes it (for one release).
+ *
+ * @deprecated Write {@link PersonAffiliation}.
+ */
+export interface LegacyPersonAffiliation {
     organization: string;
-    /** The person's role or title there (schema.org `roleName`), when known. */
     role?: string;
 }
 /**
@@ -59,7 +84,7 @@ export interface Person {
     image?: string;
     /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
     sameAs?: string[];
-    /** Organizations this person is affiliated with, each with an optional role (#1930). */
+    /** Affiliations: each a schema.org OrganizationRole, an organization with a title and dates (#2039). */
     affiliation?: PersonAffiliation[];
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
@@ -69,12 +94,65 @@ export interface Person {
  * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
+/**
+ * What `IdentityManager.update` takes: a {@link PersonUpdate} whose
+ * `affiliation` (the whole list) may still hold entries in the old
+ * `{ organization, role? }` shape, converted at the door, for one release (#2039).
+ */
+export type PersonChange = Omit<PersonUpdate, 'affiliation'> & {
+    affiliation?: Array<PersonAffiliation | LegacyPersonAffiliation>;
+};
 /**
  * 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.
  */
-export type PersonInput = PersonUpdate & {
+export type PersonInput = PersonChange & {
     identifier?: string;
 };
+/** A phone as a user typed it (#2073): the number, the country to read it with, and an extension. */
+export interface PhoneInput {
+    number?: string;
+    /** ISO 3166-1 alpha-2; the configured default country when left out. Ignored for a number typed with a leading `+`. */
+    country?: string;
+    extension?: string;
+}
+/** An address as a user typed it (#2073). Every field empty removes the address. */
+export interface AddressInput {
+    streetAddress?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+    /** ISO 3166-1 alpha-2; the configured default country when left out. */
+    addressCountry?: string;
+}
+/**
+ * What `IdentityManager.updateContactDetails` takes (#2073): the parts of an
+ * identity record a user keeps on /profile. A part left out is not touched;
+ * a text given empty is removed.
+ */
+export interface ContactDetailsInput {
+    givenName?: string;
+    familyName?: string;
+    /** Phones by `contactType` (`home`, `mobile`, `business`, `other`, or any other kind). */
+    phones?: Array<PhoneInput & {
+        contactType: string;
+    }>;
+    /** The `emergency` ContactPoint: who to call, their phone and email. */
+    emergency?: {
+        name?: string;
+        email?: string;
+        phone?: PhoneInput;
+    };
+    /** The home address (`address`). */
+    address?: AddressInput;
+    /** The `mailing` PostalAddress in `contactPoint`. */
+    mailing?: AddressInput;
+    /** Languages, each a name ("Spanish") or a tag ("es"); stored as tags. */
+    knowsLanguage?: string[];
+    /** A photo: a web address. */
+    image?: string;
+    /** Links: web addresses. */
+    sameAs?: string[];
+}

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

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

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

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

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

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

package/lib/src/utils/addonHost.js

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

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

@@ -54,6 +54,10 @@ export declare const AUDIT_EVENT: {
     readonly CONSENT_GRANT: "consent-grant";
     /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     readonly CONSENT_WITHDRAW: "consent-withdraw";
+    /** A user's new email was confirmed by its emailed link and saved (#2073). Names only, never an address */
+    readonly EMAILCHANGE_CONFIRM: "emailchange-confirm";
+    /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
+    readonly EMAILCHANGE_REQUEST: "emailchange-request";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
@@ -132,6 +136,14 @@ export declare const AUDIT_EVENT: {
     readonly REAUTH_PROMPT: "reauth-prompt";
     /** Step-up: the user re-authenticated, with the factor used */
     readonly REAUTH_SUCCESS: "reauth-success";
+    /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    readonly REVIEW_APPROVED: "review-approved";
+    /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
+    readonly REVIEW_FAILED: "review-failed";
+    /** A request was filed for review (#2072): who filed it, its id, kind, the add-on handler and the permission whose holders decide; never its summary or details */
+    readonly REVIEW_FILED: "review-filed";
+    /** A request was rejected (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    readonly REVIEW_REJECTED: "review-rejected";
     /** Page search; not recorded, read volume */
     readonly SEARCH_PAGE: "search-page";
     /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */

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

@@ -61,6 +61,10 @@ export const AUDIT_EVENT = {
     CONSENT_GRANT: 'consent-grant',
     /** A user's acceptances ended (#1603): today only when their account is deleted, which removes their consent records; names the documents and versions they had accepted. Recorded before the records are removed */
     CONSENT_WITHDRAW: 'consent-withdraw',
+    /** A user's new email was confirmed by its emailed link and saved (#2073). Names only, never an address */
+    EMAILCHANGE_CONFIRM: 'emailchange-confirm',
+    /** A user asked to change their own email: a confirmation link was sent to the new address (#2073). Names only, never an address */
+    EMAILCHANGE_REQUEST: 'emailchange-request',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** Identity record or organization created, changed, deleted or linked to an account (recorded as contact-manage before #2038); metadata names the kind (person or organization), the operation and the fields changed, never their values */
@@ -139,6 +143,14 @@ export const AUDIT_EVENT = {
     REAUTH_PROMPT: 'reauth-prompt',
     /** Step-up: the user re-authenticated, with the factor used */
     REAUTH_SUCCESS: 'reauth-success',
+    /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    REVIEW_APPROVED: 'review-approved',
+    /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
+    REVIEW_FAILED: 'review-failed',
+    /** A request was filed for review (#2072): who filed it, its id, kind, the add-on handler and the permission whose holders decide; never its summary or details */
+    REVIEW_FILED: 'review-filed',
+    /** A request was rejected (#2072): who decided, its id, kind and handler; never the note, summary or details */
+    REVIEW_REJECTED: 'review-rejected',
     /** Page search; not recorded, read volume */
     SEARCH_PAGE: 'search-page',
     /** Users searched for; enumerating users is disclosive in a way searching pages is not. Off by default as read volume */

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

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

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

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

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

@@ -24,12 +24,27 @@ export interface RoleGrants {
     /** Actions a deny policy names for this role. */
     denies: string[];
 }
+/** A grant to one subject, with the policies that give it (#2067). */
+export interface SubjectGrant extends RoleGrant {
+    /** The ids of the allow policies that give it, lowest priority first. */
+    by: string[];
+}
+export interface SubjectGrants {
+    allows: SubjectGrant[];
+    /** Actions a deny policy names for this subject. */
+    denies: string[];
+}
 /**
  * Every role a policy names, with what its policies allow and deny — the one
  * reading of "what a role grants" (#1539): the user forms, the profile, the
  * admin roles page and `PolicyDecisionPoint.rolePermissions` all come from
- * here. Policies are applied lowest priority first, so a deny takes away what
- * a lower-priority allow gave and an allow above it gives it back — the order
- * the evaluator's first-match-by-priority decides in.
+ * here.
  */
 export declare function roleGrants(policies: readonly Policy[]): Record<string, RoleGrants>;
+/**
+ * Every scheduled job a policy names (`{ "type": "job", "value": "<job id>" }`,
+ * #1999), with what its policies allow and deny and which policy gives each
+ * allow — the admin roles page's Jobs part (#2067). A job a policy names acts
+ * as itself and holds only these. Display only, like {@link roleGrants}.
+ */
+export declare function jobGrants(policies: readonly Policy[]): Record<string, SubjectGrants>;

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

@@ -0,0 +1,116 @@
+/**
+ * resolveSessionSecurity — keep `session.secure` and `trust proxy` consistent (#1046).
+ *
+ * #1043 made the session cookie `secure` actually turn on in production. On
+ * every HTTPS deployment that terminates TLS upstream — Cloudflare, an ingress,
+ * a tunnel — that silently broke login:
+ *
+ *   1. `secure` resolves true, so express-session will only emit `Set-Cookie`
+ *      on a connection it believes is https.
+ *   2. `trust proxy` defaults to false, so Express reads the raw socket and
+ *      believes the connection is plain http. It is not wrong — the hop from
+ *      the proxy really is http; it simply has not been told to read
+ *      X-Forwarded-Proto.
+ *   3. No session cookie ever reaches the browser. Every following request
+ *      builds a fresh session, so `req.session.csrfToken` is missing and the
+ *      CSRF middleware answers `403 Forbidden — invalid CSRF token` — on
+ *      `POST /login` included. Nobody can sign in.
+ *
+ * The two settings are not independent, so they are resolved together here.
+ * Turning on `secure` without `trust proxy` is not a working configuration;
+ * `secure` is the operator's stated intent to be behind TLS, and behind
+ * terminated TLS `trust proxy` is what makes Express able to see it.
+ *
+ * The operator's explicit choice still wins for both keys. The shipped
+ * app-default-config.json pins `ngdpbase.session.secure` and
+ * `ngdpbase.server.trust-proxy` to false, so a plain getProperty() read cannot
+ * tell "operator asked for false" from "nobody has said anything" — hence
+ * reading getCustomProperties() rather than the merged view.
+ *
+ * ## #1160 — native TLS breaks the assumption
+ *
+ * All of the above assumed `secure: true` meant TLS terminated UPSTREAM, so a
+ * proxy existed whose `X-Forwarded-Proto` Express had to be told to read. #1153
+ * made the server able to terminate TLS itself, and then there is no proxy —
+ * and trusting a forwarded header that nothing sets is worse than not trusting
+ * it. With `trust proxy` on and nothing in front, a caller can assert their own
+ * address and scheme, which the login throttle counts by and the audit log
+ * records.
+ *
+ * So the derivation now asks what is actually true rather than inferring from
+ * `secure` alone. The same applies to the misconfiguration warning: `secure`
+ * with `trust-proxy` explicitly false is the CORRECT configuration under native
+ * TLS, and warning about it would train an operator to ignore a warning that is
+ * load-bearing in the upstream case.
+ */
+/** Express's accepted `trust proxy` values: off, hop count, or a subnet list. */
+export type TrustProxyValue = boolean | number | string;
+/** What the resolution needs to know about the transport (#1160). */
+export interface SessionSecurityContext {
+    /**
+     * True when this server terminates TLS itself (#1153).
+     *
+     * Defaults to false so every existing caller keeps its pre-#1160 behaviour
+     * rather than silently changing what it resolves.
+     */
+    nativeTls?: boolean;
+}
+export interface SessionSecurity {
+    /** Value for the session cookie's `secure` flag. */
+    secure: boolean;
+    /** Value for `app.set('trust proxy', …)`. `false` means do not set it. */
+    trustProxy: TrustProxyValue;
+    /** True when `trustProxy` was derived from `secure` rather than configured. */
+    trustProxyDerived: boolean;
+    /**
+     * True when the resolved pair cannot issue a session cookie behind
+     * terminated TLS — `secure` on with `trust proxy` explicitly off. Only
+     * reachable when the operator configured that combination by hand; the
+     * caller is expected to log it loudly rather than silently "fix" a stated
+     * choice.
+     */
+    misconfigured: boolean;
+}
+/**
+ * Resolve the session cookie's `secure` flag and the matching `trust proxy`.
+ *
+ * `secure`: the operator's explicit boolean, else on when NODE_ENV is
+ * production. Inferring it from the request would get the terminated-TLS case
+ * exactly backwards, which is the case that matters.
+ *
+ * `trustProxy`: the operator's explicit value, else `true` whenever `secure`
+ * ends up on. `true` — rather than a hop count — because req.ip must come out
+ * as the end client. Under `1` behind Cloudflare, req.ip would resolve to the
+ * edge address shared by every visitor, and the login throttle's `ip:` bucket
+ * (#1044) would lock out all users at once on ten failures from anyone. An
+ * operator whose instance is also reachable directly should pin a hop count or
+ * a subnet list, since X-Forwarded-For is client-spoofable on that path.
+ *
+ * @param customProperties operator overrides only — NOT the merged config
+ * @param nodeEnv typically process.env.NODE_ENV
+ */
+export declare function resolveSessionSecurity(customProperties: Record<string, unknown> | null | undefined, nodeEnv: string | undefined, context?: SessionSecurityContext): SessionSecurity;
+/**
+ * #2071 — what an administrator and a visitor are told when the session
+ * cookie cannot reach the browser, spelled once: the server log, the admin
+ * dashboard, the CSRF refusal and the login page all say this.
+ */
+export declare const SESSION_COOKIE_WITHHELD_MESSAGE: string;
+/** The two request fields the check reads; express's Request has both. */
+export interface SessionCookieRequest {
+    secure?: boolean;
+    session?: {
+        cookie?: {
+            secure?: unknown;
+        };
+    } | null;
+}
+/**
+ * True when express-session will NOT send the session cookie on this request
+ * (#2071): the cookie is `secure` and the request is not https as Express
+ * sees it, after `trust proxy`. express-session makes exactly this check and
+ * then silently sends nothing, so the browser has no session, every POST
+ * meets a fresh one, and the CSRF middleware refuses it. A boolean read of
+ * two fields, cheap enough for every request.
+ */
+export declare function sessionCookieWithheld(req: SessionCookieRequest): boolean;

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

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

package/package.json

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