@jwilleke/ngdpbase-types 5.28.0 → 5.29.0

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.

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

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