@jwilleke/ngdpbase-types 5.28.0 → 5.29.1

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

@@ -42,6 +42,6 @@ export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
 export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
 export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
-export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.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/ApiContext.d.ts

@@ -40,21 +40,34 @@ export declare class ApiError extends Error {
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
     readonly reauth?: string | undefined;
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    readonly consent?: string | undefined;
     constructor(status: number, message: string, 
     /**
      * For a step-up refusal (#1745): where the person re-authenticates,
      * returning to the page they were on. Send it with the 403 so the page can
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
-    reauth?: string | undefined);
+    reauth?: string | undefined, 
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    consent?: string | undefined);
 }
 /**
  * Send a refusal — the one way it reaches the client, from core routes and
  * every add-on route alike (#1749). JSON is `{ success: false, error, reauth? }`;
  * text is the message, then where to sign in again for a step-up refusal.
- * `page` is for a link the person followed in the browser: a step-up refusal
- * redirects to the re-authenticate page, a 401 to sign-in (returning here),
- * anything else is the message as text. A route never writes its own refusal:
+ * `page` is for a link the user followed or a form they sent in the browser:
+ * a step-up refusal redirects to the re-authenticate page, a consent refusal
+ * to the consent prompt (#2027), a 401 to sign-in (returning here), anything
+ * else is the message as text. JSON carries the consent link as `consent`. A route never writes its own refusal:
  * the step-up `reauth` is easy to drop.
  */
 export declare function sendApiError(res: Response, err: ApiError, mode?: ReauthMode): void;

package/lib/src/context/ApiContext.js

@@ -4,6 +4,7 @@
 import '../types/express.js';
 import { BaseContext } from './BaseContext.js';
 import { STEP_UP_REASON } from '../types/Policy.js';
+import { CONSENT_PATH } from '../types/Consent.js';
 // ── ApiError ────────────────────────────────────────────────────────────────
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
@@ -12,16 +13,24 @@ import { STEP_UP_REASON } from '../types/Policy.js';
 export class ApiError extends Error {
     status;
     reauth;
+    consent;
     constructor(status, message, 
     /**
      * For a step-up refusal (#1745): where the person re-authenticates,
      * returning to the page they were on. Send it with the 403 so the page can
      * offer the way forward, as core routes do (`{ error, reauth }`).
      */
-    reauth) {
+    reauth, 
+    /**
+     * For a refusal because the user has documents to accept (#2027): this
+     * site's consent prompt, returning to the page they were on. Sent with
+     * the 403 as `consent`; a page is redirected there.
+     */
+    consent) {
         super(message);
         this.status = status;
         this.reauth = reauth;
+        this.consent = consent;
         this.name = 'ApiError';
     }
 }
@@ -29,19 +38,26 @@ export class ApiError extends Error {
  * Send a refusal — the one way it reaches the client, from core routes and
  * every add-on route alike (#1749). JSON is `{ success: false, error, reauth? }`;
  * text is the message, then where to sign in again for a step-up refusal.
- * `page` is for a link the person followed in the browser: a step-up refusal
- * redirects to the re-authenticate page, a 401 to sign-in (returning here),
- * anything else is the message as text. A route never writes its own refusal:
+ * `page` is for a link the user followed or a form they sent in the browser:
+ * a step-up refusal redirects to the re-authenticate page, a consent refusal
+ * to the consent prompt (#2027), a 401 to sign-in (returning here), anything
+ * else is the message as text. JSON carries the consent link as `consent`. A route never writes its own refusal:
  * the step-up `reauth` is easy to drop.
  */
 export function sendApiError(res, err, mode = 'json') {
     // Only this site's re-authenticate page: an add-on's ApiError cannot send the person elsewhere.
     const reauth = typeof err.reauth === 'string' && err.reauth.startsWith('/auth/reauth?') ? err.reauth : undefined;
+    // Likewise only this site's consent prompt.
+    const consent = typeof err.consent === 'string' && (err.consent === CONSENT_PATH || err.consent.startsWith(`${CONSENT_PATH}?`)) ? err.consent : undefined;
     if (mode === 'page') {
         if (reauth) {
             res.redirect(reauth);
             return;
         }
+        if (consent) {
+            res.redirect(consent);
+            return;
+        }
         if (err.status === 401) {
             res.redirect('/login?redirect=' + encodeURIComponent(res.req?.originalUrl || '/'));
             return;
@@ -50,10 +66,10 @@ export function sendApiError(res, err, mode = 'json') {
         return;
     }
     if (mode === 'text') {
-        res.status(err.status).send(reauth ? `${err.message}: ${reauth}` : err.message);
+        res.status(err.status).send(reauth ? `${err.message}: ${reauth}` : consent ? `${err.message} Read and accept them at ${consent}` : err.message);
         return;
     }
-    res.status(err.status).json({ success: false, error: err.message, ...(reauth ? { reauth } : {}) });
+    res.status(err.status).json({ success: false, error: err.message, ...(reauth ? { reauth } : {}), ...(consent ? { consent } : {}) });
 }
 /**
  * The subject a request carries, refused when there is none (#1399).

package/lib/src/ice/runImport.d.ts

@@ -43,6 +43,32 @@ export interface ChainSpec {
  * warnings first. Partial notes are collected into `partial`.
  */
 export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+/** Does this run keep its originals during the upload (#2034)? */
+export declare function keepsAtUpload(receiver: RegisteredReceiver | undefined, original: OriginalChoice): boolean;
+/** What keeping at upload did: how many it kept, or the first file it could not keep. */
+export interface UploadKeepResult {
+    kept: number;
+    refused?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Keep the originals of a run whose receiver keeps into an encrypted store,
+ * now, during the upload (#2034). `ctx` is the REQUEST's context: it holds
+ * the user's unlocked key, so the receiver's `keepOriginal` seals the bytes
+ * and the store's sealed index entry while the key is live. Each kept
+ * original is recorded in the ledger by fingerprint and door (#2011), so the
+ * queued run reuses it and never keeps again.
+ *
+ * The files are decided exactly as the run decides them ({@link planFile}):
+ * noise, a file too large, one nothing reads and one already imported are
+ * not kept. An original already kept through this door is not kept again.
+ * Stops at the first refusal (or failure) and says which file: the caller
+ * then queues nothing. Originals kept before it stay kept, and recorded, so
+ * the next try reuses them.
+ */
+export declare function keepOriginalsAtUpload(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, scope: string): Promise<UploadKeepResult>;
 /**
  * Run one import. Fills and returns `report`, which the caller may be
  * showing while it runs. Never throws for one file's failure; that file's

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

@@ -182,6 +182,13 @@ export interface IceReceiver {
      * store). Without this, `keep` hands the original to the files receiver.
      */
     keepOriginal?(original: IceItem, ctx: ActorContext): 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
+     * keeps each original during the upload, with the request's own context,
+     * before the run is queued; the run reuses what was kept and needs no key.
+     */
+    keepsEncrypted?: boolean;
     /** The original-file choices this receiver offers (D11). Without it: all three. */
     originals?: IceOriginalChoices;
 }

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

@@ -31,7 +31,7 @@ import BaseManager, { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { IContentConverter } from '../converters/IContentConverter.js';
 import { type ZipReadLimits } from '../utils/zipArchive.js';
-import type { JobContext } from '../context/JobContext.js';
+import { type JobContext } from '../context/JobContext.js';
 import type { IceLedger, IceOriginalChoices, IceReceiver, IceRunReport, IceRunRequest, IceShim, RegisteredShim } from '../ice/types.js';
 /**
  * Options for import operations
@@ -207,6 +207,16 @@ export declare class TakeoutImportRefused extends Error {
     readonly reason: 'not-owner' | 'no-such-store' | 'locked' | 'unreadable';
     constructor(reason: 'not-owner' | 'no-such-store' | 'locked' | 'unreadable', message: string);
 }
+/**
+ * An import refused at upload, before anything was queued (#2034): keeping
+ * the original of `file` in the receiver's encrypted store was refused or
+ * failed. `message` is written for the user who uploaded.
+ */
+export declare class ImportUploadRefused extends Error {
+    readonly file: string;
+    readonly reason: string;
+    constructor(file: string, reason: string);
+}
 /** One page's outcome in a takeout import (#1472). */
 export type TakeoutPageOutcome = {
     title: string;
@@ -344,11 +354,27 @@ declare class ImportManager extends BaseManager {
     runImport(request: IceRunRequest, ctx: ActorContext): Promise<IceRunReport>;
     /**
      * Queue an import as background work and return its run id at once. The
-     * run carries `ctx` — the person who asked (`jobContextFromRequest`), or a
+     * run carries `ctx` — the user who asked (`jobContextFromRequest`), or a
      * job's context with its reason — and each receiver checks its own
-     * permission with it when the run reaches it (D5).
+     * permission with it when the run reaches it (D5). A user's upload, from
+     * a request, goes through {@link enqueueUpload} instead.
      */
     enqueueImport(request: IceRunRequest, ctx: JobContext): Promise<string>;
+    /**
+     * Queue a user's upload, from the request it arrived in (#2034). `ctx` is
+     * the REQUEST's context; the run carries the job context derived from it
+     * (`jobContextFromRequest`), as {@link enqueueImport} does.
+     *
+     * When the run keeps originals through a receiver that keeps into an
+     * encrypted store (`keepsEncrypted`), they are kept first, here, with
+     * `ctx`, while the user's key is in the request: the bytes are sealed and
+     * the store's sealed index entry written. Each is recorded in the ledger
+     * as the keep-once record (#2011), so the run reuses it and needs no key.
+     *
+     * @throws ImportUploadRefused when an original could not be kept; nothing is queued
+     */
+    enqueueUpload(request: IceRunRequest, ctx: ActorContext): Promise<string>;
+    private enqueueResolved;
     /** A run's report, to the person it runs as; null to anyone else. */
     getImportRun(runId: string, ctx: ActorContext): IceRunReport | null;
     /** The runs this process holds for the user `ctx` names, newest first (#2021): their own, never anyone else's. */
@@ -357,6 +383,8 @@ declare class ImportManager extends BaseManager {
     setImportLedger(ledger: IceLedger): void;
     private newRunReport;
     private executeRun;
+    /** What a run, or keeping at upload, works with. */
+    private iceDeps;
     private enabledShims;
     /**
      * Hand the queue to the background job. One job run drains every queued

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

@@ -37,8 +37,8 @@ export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' |
  * person keeps its `@id` and takes the account; the person made for the new
  * account is folded into it and removed, so there is never a second person.
  *
- * `getByUserIdentifier(ctx, username)` remains as a lazy-migration entry
- * point for legacy users that pre-date the sync wiring.
+ * `getByUserIdentifier(ctx, username)` returns a user's identity record and
+ * makes it when the user has none (#2037): every user has exactly one.
  */
 declare class PersonManager extends BaseManager {
     readonly description = "Canonical Person records (#617)";
@@ -51,6 +51,8 @@ declare class PersonManager extends BaseManager {
     private metricsRef;
     /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
     private linkOffers;
+    /** #2037: making a user's missing identity record, one at a time per username. */
+    private readonly accountRecords;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** `ngdpbase.application.persons.storagedir`, resolved: where the records are. */
@@ -155,13 +157,20 @@ declare class PersonManager extends BaseManager {
      */
     invalidateCache(): void;
     /**
-     * Lazy-migration entry point.
+     * The identity record of the user `username`, made when the user has none
+     * (#2037). Every user has exactly one identity record; one made outside
+     * `UserManager.createUser` (an account written straight into the user
+     * store) gets it here, from the account's display name and email.
      *
-     * Returns the Person paired to `username`. If none exists and a matching
-     * User does, a Person is created from the User's email/displayName and
-     * persisted. Subsequent calls return the persisted record. Decided as
-     * {@link getByIdentifier} (#2018): a signed-in user's own under
-     * `profile-manage` ("your receipts"), anyone else's under `contact-read`.
+     * The read is decided as {@link getByIdentifier} (#2018): a signed-in user's
+     * own under `profile-manage`, anyone else's under `contact-read`, core's own
+     * work under the system context. Making the missing record is core's
+     * bookkeeping, not the caller's contact management, so it goes through
+     * {@link create} under the system context, naming the caller, and is
+     * recorded as `contact-manage`. One at a time per username, so two lookups
+     * never make two records. Null when there is no account by that name.
+     * Never a second record: a contact with the same email is left alone
+     * (an administrator links it, {@link linkAccount}).
      */
     getByUserIdentifier(ctx: ActorContext, username: string): Promise<Person | null>;
     private requireProvider;

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

@@ -67,8 +67,9 @@ declare class RoleManager extends BaseManager {
      * The pseudo-roles `'Authenticated'` and `'All'` are NOT added here — the
      * caller adds those when constructing `userContext.roles`.
      *
-     * Returns `[]` when PersonManager is unavailable, the user has no Person
-     * record, no record lists them, or the lookup throws.
+     * Returns `[]` when PersonManager is unavailable, there is no account by
+     * that username, no record lists them, or the lookup throws. An account
+     * missing its identity record gets it here (#2037).
      *
      * `ctx` is who is asking (#2018), decided by PersonManager's door: a user
      * about themselves under `profile-manage`, about anyone else under

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

@@ -340,6 +340,17 @@ declare class UserManager extends BaseManager {
     private withAccountRoles;
     /** `ngdpbase.user.account-roles`: the roles every account holds (#1539). */
     private accountRoles;
+    /**
+     * Every account has exactly one identity record, made by `createUser`
+     * (#2037). One that has none (written straight into the user store, or
+     * whose record was lost) gets it at boot, once, through PersonManager's
+     * door under the system context, each creation recorded as
+     * `contact-manage`. The identity records are listed once and only the
+     * missing ones are made, so a large user store costs one read. A failure
+     * is logged and the boot goes on: the role paths make the record when the
+     * account is next used (`getByUserIdentifier`).
+     */
+    private giveIdentityRecordsToAccountsWithout;
     /**
      * Accounts made before a role joined `ngdpbase.user.account-roles` get it
      * once, at boot (#1539) — RoleManager decides "once" and records each grant.
@@ -506,6 +517,11 @@ declare class UserManager extends BaseManager {
     /**
      * Search users by username, displayName, or email (case-insensitive substring).
      * Optionally filter by role and active status.
+     *
+     * Decides `search-user` itself, with `ctx` (#2018): every user holds it as
+     * shipped, anonymous does not. A refusal throws `ContactRefusedError`. Core's
+     * own lookups (a notice's recipients, a role's holders) pass the system
+     * context with a reason, allowed without a policy evaluation.
      */
     searchUsers(query: string, options: {
         role?: string;

package/lib/src/types/Consent.js

@@ -0,0 +1,22 @@
+/**
+ * Consent to a site's documents (#1603): the shapes ConsentManager and its
+ * callers share, and what an add-on registers.
+ */
+/** Where a person is asked to accept (#1603): `?scope=` (core when absent) and `?returnTo=`. */
+export const CONSENT_PATH = '/consent';
+/** The scope of core's own documents, `ngdpbase.consent.documents`. */
+export const CORE_CONSENT_SCOPE = 'core';
+/**
+ * Thrown when a per-person add-on is turned on before its documents are
+ * accepted (#1603). `documents` names what is still to accept.
+ */
+export class ConsentRequiredError extends Error {
+    scope;
+    documents;
+    name = 'ConsentRequiredError';
+    constructor(scope, documents) {
+        super(`Turning ${scope} on needs its ${documents.join(' and ')} accepted first`);
+        this.scope = scope;
+        this.documents = documents;
+    }
+}

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

@@ -12,11 +12,15 @@
  * @see https://schema.org/Organization
  */
 /**
- * Schema.org PostalAddress (subset used by Organization)
+ * Schema.org PostalAddress (subset used by Organization/Person).
+ *
+ * In schema.org a PostalAddress is a ContactPoint, so it carries the
+ * ContactPoint fields too: a `contactPoint[]` entry may be one (a mailing or
+ * business address, with its `contactType`, `name` and `telephone`).
  *
  * @see https://schema.org/PostalAddress
  */
-export interface PostalAddress {
+export interface PostalAddress extends Omit<ContactPoint, '@type'> {
     '@type': 'PostalAddress';
     streetAddress?: string | null;
     addressLocality?: string | null;
@@ -32,11 +36,19 @@ export interface PostalAddress {
 export interface ContactPoint {
     '@type': 'ContactPoint';
     contactType?: string;
+    /** 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;
     telephone?: string;
     url?: string;
     availableLanguage?: string[];
 }
+/**
+ * One `contactPoint[]` entry: a ContactPoint, or a PostalAddress (schema.org's
+ * ContactPoint subtype). Typed by `contactType` (`mailing`, `business`,
+ * `agent`, `emergency`, …); the home address stays in `address`.
+ */
+export type ContactPointEntry = ContactPoint | PostalAddress;
 /**
  * Canonical Organization record.
  *
@@ -62,8 +74,8 @@ export interface Organization {
     foundingDate?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (support, sales, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Contact points (support, sales, a mailing address, etc.) */
+    contactPoint?: ContactPointEntry[];
     /** Other URLs that identify this org (LinkedIn, Twitter, etc.) */
     sameAs?: string[];
     /** Optional legacy slug or external identifier */

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

@@ -15,7 +15,7 @@
  *
  * @see https://schema.org/Person
  */
-import type { PostalAddress, ContactPoint } from './Organization.js';
+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.
@@ -51,8 +51,8 @@ export interface Person {
     email?: string;
     /** Postal address */
     address?: PostalAddress;
-    /** Contact points (work phone, mobile, etc.) */
-    contactPoint?: ContactPoint[];
+    /** Everything but the home address: phones, a mailing or business address (a PostalAddress), an agent, an emergency contact; each typed by `contactType`. */
+    contactPoint?: ContactPointEntry[];
     /** ISO language tags this person knows */
     knowsLanguage?: string[];
     /** Profile/avatar image URL */

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

@@ -67,6 +67,13 @@ export declare function isSystemWork(engine: EngineLike, ctx: ActorContext | nul
 export declare function requireRecordAccess(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, record?: {
     identifier?: unknown;
 } | null): Promise<void>;
+/**
+ * A lookup of users (#2018): `UserManager.searchUsers` asks `permission`
+ * (`search-user`) with the caller's context, and throws
+ * {@link ContactRefusedError} on a refusal. Core's own work
+ * ({@link isSystemWork}) is allowed without a policy evaluation.
+ */
+export declare function requireLookupPermission(engine: EngineLike, ctx: ActorContext, permission: CorePermission): Promise<void>;
 /** What a contacts record says was done. Names fields, never their values. */
 export interface ContactChange {
     kind: 'person' | 'organization';

package/package.json

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