@jwilleke/ngdpbase-types 5.30.1 → 5.31.0

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

@@ -41,12 +41,12 @@ export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection,
 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/managers/BackgroundJobManager.d.ts

@@ -327,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/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/UserManager.d.ts

@@ -222,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
      *
@@ -255,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/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,20 @@ 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;
 };

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.30.1",
+  "version": "5.31.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",