@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

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

@@ -1,7 +1,8 @@
 import BaseManager from './BaseManager.js';
 import type { Policy, PolicySubject, PolicyResource, PolicyCondition } from '../types/Policy.js';
-import { type DeclaredSubjectAttribute } from '../utils/policyAttributes.js';
+import { type DeclaredEnvironmentAttribute, type DeclaredSubjectAttribute } from '../utils/policyAttributes.js';
 import { WikiEngine } from '../types/WikiEngine.js';
+import type { ActorContext } from '../context/ActorContext.js';
 /**
  * User context for policy evaluation
  */
@@ -43,28 +44,34 @@ interface AccessContext {
     readAttribute?: AttributeReader;
 }
 /**
- * What is wrong with a policy's condition, one sentence each (#2255, #2261);
- * empty when it is fine. Each sentence says what is wrong, then what to
- * change. A node is a comparison (`attribute` and one operator) or `any-of`,
- * `all-of` or `not` over other conditions, nested at most
- * {@link MAX_CONDITION_DEPTH} deep, at most {@link MAX_CONDITION_NODES} nodes
- * in all, an `in` list of at most {@link MAX_IN_ITEMS} and an `any-of` or
- * `all-of` of at most {@link MAX_GROUP_CHILDREN}. Each attribute a comparison names must be
- * declared: a `subject:<name>` in `ngdpbase.access.subject-attributes`
- * (`id` always, `aal` as shipped), or a `resource:<name>` declared on the `page`
- * resource type. The types of the two sides must agree. A condition with a
- * problem never holds: an allow with it does not apply and a deny with it
- * does, as for a missing attribute.
+ * What is wrong with a policy's condition, one sentence each (#2255, #2261,
+ * #2330); empty when it is fine. Each sentence says what is wrong, then what to
+ * change. A node is one XACML function in lowercase: a comparison such as
+ * `string-equal` over two arguments, or `and`, `or` or `not` over other
+ * conditions, nested at most {@link MAX_CONDITION_DEPTH} deep, at most
+ * {@link MAX_CONDITION_NODES} function nodes in all, an `is-in` list of at most
+ * {@link MAX_IN_ITEMS} and an `and` or `or` of at most {@link MAX_GROUP_CHILDREN}.
+ * An argument is an attribute (`attributeid`, `datatype`) or a literal (`value`,
+ * `datatype`); `datatype` is required, must be the type the attribute is declared with
+ * and the type the function takes. Each attribute must be declared: a
+ * `subject:<name>` in `ngdpbase.access.subject-attributes` (`id` always, `aal`
+ * as shipped), or a `resource:<name>` declared on the resource type the policy names (the
+ * `page` type when it names a page, or that add-on's type when it names only
+ * that type, #1823), or an `environment:<name>` in `ngdpbase.access.environment-attributes`. The old
+ * shape (`attribute` with `equals` and the like) is a problem that shows the
+ * new one. A condition with a problem never holds: an allow with it does not
+ * apply and a deny with it does, as for a missing attribute.
  */
 export declare function conditionProblems(condition: unknown, pageAttributes: Record<string, {
     type?: string;
-}>, subjectAttributes?: Record<string, DeclaredSubjectAttribute>): string[];
+}>, subjectAttributes?: Record<string, DeclaredSubjectAttribute>, environmentAttributes?: Record<string, DeclaredEnvironmentAttribute>, resourceTypeLabel?: string): string[];
 /**
  * Is the condition true, false or unknown (#2255, #2261)? `true` or `false`,
  * or `undefined` when it cannot be told because an attribute it reads is
- * missing; the caller fails closed on that. Each node is judged on its own:
- * a missing attribute makes its leaf unknown, a true branch decides `any-of`,
- * a false branch decides `all-of`, and `not` of unknown is unknown.
+ * missing, or an argument lacks the datatype its function takes; the caller
+ * fails closed on that. Each node is judged on its own: a missing attribute
+ * makes its comparison unknown, a true branch decides `or`, a false branch
+ * decides `and`, and `not` of unknown is unknown.
  */
 export declare function conditionHolds(condition: PolicyCondition | undefined, read: AttributeReader | undefined, depth?: number): Promise<boolean | undefined>;
 /**
@@ -87,6 +94,25 @@ export declare const SUBJECT_MATCHERS: Record<string, (value: string | undefined
  * on one is refused rather than ignored.
  */
 export declare const VALUELESS_SUBJECT_TYPES: readonly string[];
+/**
+ * Which resource attributes a policy's condition may read (#1823).
+ *
+ * A policy that names exactly one add-on type (no page matcher) uses that
+ * type's attributes. A policy on a core type, including `system-category`,
+ * still reads the `page` attributes: those conditions are about the page.
+ */
+export declare function conditionAttributeSource(resources: readonly {
+    type?: string;
+}[] | undefined, types: Record<string, {
+    attributes?: Record<string, {
+        type?: string;
+    }>;
+}> | null): {
+    attributes: Record<string, {
+        type?: string;
+    }>;
+    label: string;
+};
 /**
  * The resource types configuration declares (#1504), for the evaluator and the
  * validator alike. When the key is not set at all — a configuration older than
@@ -112,8 +138,8 @@ interface EvaluationResult {
  *
  * PolicyEvaluator mimics how JSPWiki uses Java's built-in security framework
  * (java.security) to load and evaluate security policies from a policy file.
- * Among the policies that match, a deny overrides any allow whatever its
- * priority, and no match is a deny (#2255). Each decision names the policies
+ * Among the policies that match, a deny overrides any allow, the
+ * rule-combining algorithm `deny-overrides` (#2330), and no match is a deny (#2255). Each decision names the policies
  * that decided it.
  *
  * @class PolicyEvaluator
@@ -136,6 +162,17 @@ interface EvaluationResult {
  */
 declare class PolicyEvaluator extends BaseManager {
     private configManager;
+    /** The headline of the access-policies item now up, so marking the last deny takes down this one and no other (#2355). */
+    private reportedReason;
+    /**
+     * Each condition checked and compiled, by the condition object configuration
+     * holds (#2279), kept while `ConfigurationManager.getRevision()` is
+     * `revision`. Any change to the configuration (a save, a reload, a reset, a
+     * restore, an add-on's runtime value) changes the revision, and the next
+     * decision starts again from nothing. The policies themselves are still read
+     * live for every decision; only a condition's compiled form is reused.
+     */
+    private preparedConditions;
     /**
      * The policies in force NOW. Only the PDP interprets them (#1431 step 14b);
      * this evaluator is the PDP's matching engine and asks it for the list, read
@@ -163,29 +200,67 @@ declare class PolicyEvaluator extends BaseManager {
      */
     initialize(): Promise<void>;
     /**
-     * Say at boot what an administrator should look at in the policies after
-     * #2255, one warning each, and one needs-attention entry for them all:
-     * stored policies the upgrade rewrote, policies it left that now decide
-     * differently (a deny) or reach pushed pages, conditions that never hold,
-     * and stored categories no policy lets anyone change (their pages are
-     * changed by nobody, admin included).
+     * Say at boot what a developer should look at in the policies after #2255,
+     * one warning each: stored policies the upgrade rewrote, policies it left
+     * that now decide differently (a deny) or reach pushed pages, and conditions
+     * that never hold. These are log lines only; categories no policy lets anyone
+     * change are an upgrade check (`upgradeChecks/uneditablePages.ts`).
      */
     private reportPageWritePolicies;
+    /** The stored marks whose rule is still a deny in force (#2355). A mark for a rule since removed is not kept: the same rule added later must be shown again. */
+    private marksOfExistingDenies;
+    /** Save the marks without those of rules that are gone (#2355); nothing is written when none is. */
+    private dropMarksOfGoneRules;
+    /**
+     * An administrator marks a deny as checked (#2355). Kept as the rule's id and a fingerprint of
+     * its content in `ngdpbase.access.checked-denies`, written through ConfigurationManager with the
+     * person's context, which records the change. It hides the item and nothing else: no decision
+     * reads it. Answers `changed` when the rule is no longer what the page showed (nothing is
+     * saved) and `missing` when no deny has that id.
+     */
+    markDenyChecked(ctx: ActorContext, id: string, fingerprint: string): Promise<'checked' | 'changed' | 'missing'>;
     /**
      * Evaluates all relevant policies to make an access decision (#2255).
      *
-     * Deny overrides allow: if any matching deny applies, the answer is deny,
-     * whatever the priorities; otherwise any matching allow permits; otherwise
-     * no policy decided. A policy with a `condition` applies only when it holds;
+     * Deny overrides allow (the rule-combining algorithm, #2330): if any matching
+     * deny applies, the answer is deny; otherwise any matching allow permits;
+     * otherwise no policy decided. A policy with a `condition` applies only when it holds;
      * an unknown condition (a missing attribute) keeps an allow from applying
      * and lets a deny apply, so a missing attribute fails closed.
      */
     evaluateAccess(context: AccessContext): Promise<EvaluationResult>;
     /**
-     * Checks and compiles each policy's condition (#2261). `compile()` does it
-     * once for a whole listing; a single decision does it for its few matches.
+     * The policies with their conditions checked and compiled (#2279): a
+     * condition already compiled under the configuration in force is reused,
+     * and `prepare` runs only for the rest. With no configuration revision to
+     * key on, everything is prepared again.
+     */
+    private prepared;
+    /**
+     * Checks and compiles each policy's condition (#2261). `prepared()` keeps
+     * the result until the configuration changes (#2279).
      */
     private prepare;
+    /**
+     * Decide one add-on record type by id (#1823).
+     *
+     * Only policies that name this type are considered, and a policy with no
+     * resources does not match: a page grant cannot cover the type, and a
+     * blanket policy cannot either. The id is matched with the same globs as a
+     * page name, a leading dot included. A core type (`page`, `system-category`, `vault`,
+     * `shared-folder`) is not decided here.
+     */
+    evaluateDeclaredResource(context: {
+        resourceType: string;
+        id: string;
+        action: string;
+        actions?: readonly string[];
+        userContext?: UserContext;
+        readAttribute?: AttributeReader;
+    }): Promise<EvaluationResult>;
+    /** True when a policy resource names this type and its pattern covers the id. No resources is not a match. */
+    private namesDeclaredType;
+    private resourceTypeMap;
     /**
      * Deny overrides allow, over policies that already match subject, resource
      * and action (#2255). Every matching deny whose condition is true or
@@ -264,6 +339,14 @@ declare class PolicyEvaluator extends BaseManager {
     }>;
     /** The subject attributes a condition may read (#2261): `id` always, and those declared in `ngdpbase.access.subject-attributes`. */
     declaredSubjectAttributes(): Record<string, DeclaredSubjectAttribute>;
+    /** The environment attributes a condition may read (#2261): those declared in `ngdpbase.access.environment-attributes`. */
+    declaredEnvironmentAttributes(): Record<string, DeclaredEnvironmentAttribute>;
+    /**
+     * One line for each declared `schedule:` attribute whose schedule is not in
+     * `ngdpbase.schedules` (the attribute is missing and a condition on it fails
+     * closed) or has no rules (it reads as always open), for the boot warning.
+     */
+    private scheduleProblems;
     /** Each policy in force whose condition has a problem, with the problems (#2255): for the boot warning. */
     conditionProblemsInForce(): Array<{
         id: string;

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

@@ -5,6 +5,12 @@ export interface ThemeInfo {
     author: string;
     /** Optional Google Fonts (or other) stylesheet URLs to inject in <head> */
     fonts?: string[];
+    /**
+     * Optional CSS filenames in this theme's css/ directory. Loaded after
+     * core.css so a site theme can adjust layout without editing the shared
+     * sheet. Basenames only; paths are rejected.
+     */
+    stylesheets?: string[];
 }
 export interface ThemePaths {
     /** Active theme name (folder name under themes/) */
@@ -23,6 +29,8 @@ export interface ThemePaths {
     themeInfo: ThemeInfo | null;
     /** Optional font stylesheet URLs from theme.json fonts[] */
     fontUrls: string[];
+    /** Theme CSS files to load after core.css. Public URLs. */
+    themeStylesheets: string[];
 }
 /**
  * Returns a cached ThemeManager for the given active theme + themes directory.
@@ -44,11 +52,22 @@ export declare class ThemeManager {
     constructor(activeTheme: string, themesDir: string);
     private loadThemeInfo;
     private buildPaths;
+    /**
+     * Publish theme.json stylesheets[] as /themes/<theme>/css/<file>.
+     * Only a basename ending in .css that exists in that directory is kept,
+     * so a theme cannot point the browser at another path.
+     */
+    private resolveThemeStylesheets;
     /** Resolve variables.css path — falls back to empty placeholder if theme has no custom vars */
     private resolveVariablesCssPath;
     /** Resolve favicon path: prefer favicon.svg → favicon.png → public fallback */
     private resolveFaviconPath;
-    /** Resolve logo path: prefer logo.svg → logo.png → favicon.svg → favicon.png → public fallback */
+    /**
+     * Resolve the header logo path: prefer logo-header.svg → logo-header.png →
+     * logo.svg → logo.png → favicon.svg → favicon.png → public fallback.
+     * logo-header.* lets a theme show a different copy in the header than the
+     * logo.* file that pages may link to.
+     */
     private resolveLogoPath;
     get paths(): ThemePaths;
     /** List all available themes (subdirs of themes/ that have a theme.json) */

package/lib/src/providers/FileLoggingProvider.d.ts

@@ -21,6 +21,15 @@ declare class FileLoggingProvider extends BaseLoggingProvider {
      */
     createTransports(config: LoggingProviderConfig): Transport[];
     createFormat(): Logform.Format;
+    /** CR and LF as the visible two-character sequences `\r` and `\n`, so a value cannot start a line of its own (#2294). */
+    private static oneLine;
+    /**
+     * A stack keeps one frame per line, but its message portion (`Name: message`, which can span lines and can
+     * hold a caller-sent value) must not start a log line of its own (#2294). Only a line that begins with
+     * optional whitespace and `at ` starts a new output line; every other line is joined to the one before it
+     * with a visible `\n`.
+     */
+    private static stackLines;
     /**
      * Render whatever a caller passed as the second argument to `logger.*`.
      *
@@ -30,7 +39,9 @@ declare class FileLoggingProvider extends BaseLoggingProvider {
      * line would be noise at best.
      *
      * A `stack` is emitted on its own lines because a one-line stack is
-     * unreadable, and reading the stack is the entire reason this exists.
+     * unreadable, and reading the stack is the entire reason this exists. Its
+     * frames keep their own lines; CR and LF in its message portion are escaped,
+     * as are those in the other keys and their string values.
      *
      * @param info - The winston info object for one log record
      * @returns The rendered metadata, or an empty string when there is none

package/lib/src/providers/FileLoggingProvider.js

@@ -45,7 +45,17 @@ class FileLoggingProvider extends BaseLoggingProvider {
         // #1461: private page titles never reach a log line or /admin/logs.
         redactPrivateNamesFormat(), format.printf((info) => {
             const ts = typeof info.timestamp === 'string' ? info.timestamp : JSON.stringify(info.timestamp);
-            const msg = typeof info.message === 'string' ? info.message : JSON.stringify(info.message);
+            // #2294: a caller-sent value (a page name) in the message could carry a CR or LF and start a log line of
+            // its own. Escaped here, once, for every transport and every call site; the escape is visible, not removed.
+            // Never throws: a logger that throws breaks its caller. Any non-string message (undefined, symbol, function,
+            // a circular object) is coerced with String(), and a formatting error falls back to a fixed marker.
+            let msg;
+            try {
+                msg = FileLoggingProvider.oneLine(typeof info.message === 'string' ? info.message : String(info.message));
+            }
+            catch {
+                msg = '[unprintable log message]';
+            }
             // #1141: render the metadata too. This printf used to emit only
             // timestamp/level/message, so the second argument of every
             // `logger.error(msg, { error, stack })` call in the codebase was
@@ -57,6 +67,27 @@ class FileLoggingProvider extends BaseLoggingProvider {
             return meta ? `${ts} [${info.level}]: ${msg} ${meta}` : `${ts} [${info.level}]: ${msg}`;
         }));
     }
+    /** CR and LF as the visible two-character sequences `\r` and `\n`, so a value cannot start a line of its own (#2294). */
+    static oneLine(text) {
+        return text.replace(/[\r\n]/g, (c) => (c === '\r' ? '\\r' : '\\n'));
+    }
+    /**
+     * A stack keeps one frame per line, but its message portion (`Name: message`, which can span lines and can
+     * hold a caller-sent value) must not start a log line of its own (#2294). Only a line that begins with
+     * optional whitespace and `at ` starts a new output line; every other line is joined to the one before it
+     * with a visible `\n`.
+     */
+    static stackLines(stack) {
+        const out = [];
+        stack.split('\n').forEach((raw, i) => {
+            const line = FileLoggingProvider.oneLine(raw);
+            if (i === 0 || /^\s*at /.test(raw))
+                out.push(line);
+            else
+                out[out.length - 1] += `\\n${line}`;
+        });
+        return out.join('\n');
+    }
     /**
      * Render whatever a caller passed as the second argument to `logger.*`.
      *
@@ -66,7 +97,9 @@ class FileLoggingProvider extends BaseLoggingProvider {
      * line would be noise at best.
      *
      * A `stack` is emitted on its own lines because a one-line stack is
-     * unreadable, and reading the stack is the entire reason this exists.
+     * unreadable, and reading the stack is the entire reason this exists. Its
+     * frames keep their own lines; CR and LF in its message portion are escaped,
+     * as are those in the other keys and their string values.
      *
      * @param info - The winston info object for one log record
      * @returns The rendered metadata, or an empty string when there is none
@@ -82,10 +115,10 @@ class FileLoggingProvider extends BaseLoggingProvider {
             if (value === undefined)
                 continue;
             if (key === 'stack' && typeof value === 'string') {
-                stack = value;
+                stack = FileLoggingProvider.stackLines(value);
                 continue;
             }
-            parts.push(`${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+            parts.push(`${FileLoggingProvider.oneLine(key)}=${typeof value === 'string' ? FileLoggingProvider.oneLine(value) : JSON.stringify(value)}`);
         }
         const inline = parts.length > 0 ? parts.join(' ') : '';
         if (stack) {

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -28,6 +28,7 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import type { Decision, DecisionRequest, Policy } from '../types/Policy.js';
 import { type RoleGrant } from '../utils/roleGrants.js';
 import { type ActorContext } from '../context/ActorContext.js';
+import { type OwnedListAsk, type OwnedListDecision, type OwnedRecordAsk } from './ownedRecords.js';
 export declare const POLICIES_KEY = "ngdpbase.access.policies";
 export declare const POLICIES_ENABLED_KEY = "ngdpbase.access.policies.enabled";
 /** Whether an administrator may enter another person's unencrypted vault (#2255). */
@@ -50,7 +51,8 @@ export declare class PolicyDecisionPoint extends BaseManager {
     /** Warn, once per policy and name, that a policy names a retired permission and what it is read as (#2038). */
     private warnRetiredOnce;
     /**
-     * The policies in force right now, highest priority first.
+     * The policies in force right now, in configuration order. Order carries no
+     * meaning: the rule-combining algorithm is `deny-overrides` (#2330).
      *
      * - `ngdpbase.access.policies.enabled` false — its default when unset —
      *   means none;
@@ -73,8 +75,8 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * What each role permits: role name → the actions its holders are granted.
      *
      * It mirrors the evaluator's ROLE matching — an allow policy naming a role
-     * grants its actions, a deny policy naming it takes them away, lower
-     * priority first so a higher-priority deny lands last and wins. It does not
+     * grants its actions, a deny policy naming it takes them away, whatever the
+     * order (deny-overrides, #2330). It does not
      * evaluate resource patterns or the ceilings, so it is a summary for a human
      * reading a table (the admin Security Policy Summary, a profile), never an
      * authorisation answer — that is {@link permits} with the caller's subject.
@@ -332,6 +334,51 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * with `pushed-pages-edit` to leave pushed pages out. A summary of the
      * policies, never an answer to "may this subject".
      */
+    /**
+     * May this subject act on one stored add-on record (#1823)?
+     *
+     * The manager passes attributes it read from the row. `owner` is the
+     * identity @id. A type that declares `owner` is allowed only when that @id
+     * is the subject's (the person a proxy grant represents, not the actor),
+     * and policy also allows the action. A role does not bypass the owner. A
+     * type with no `owner` is policy alone. A core type (`page`, `vault`, …)
+     * is not decided here. Missing data throws {@link OwnedRecordError}; the
+     * caller fails closed. This records nothing.
+     */
+    decideOwnedRecord(input: DecisionInput, request: OwnedRecordAsk): Promise<Decision>;
+    /**
+     * May this subject list a type, and which rows (#1823)?
+     *
+     * An allow for a type that declares `owner` carries one filter, `owner`
+     * equals the subject's identity @id. The manager binds that value; it is
+     * not SQL. An allow for a type with no owner carries an empty filter: policy
+     * alone, no row constraint. A refusal is `{ decision: 'deny' }`, never an
+     * empty filter and never an empty row set from this method. Missing data
+     * throws {@link OwnedRecordError}. This records nothing: the list is logged
+     * once by the manager that applies it.
+     */
+    decideOwnedList(input: DecisionInput, request: OwnedListAsk): Promise<OwnedListDecision>;
+    /**
+     * The ceilings, the declared type, and a reader for conditions. A ceiling
+     * denial is the whole answer. Anything that cannot be decided throws.
+     */
+    private prepareOwned;
+    private ownedTypeEntry;
+    private typeDeclaresOwner;
+    /** The owner the manager read. Missing on an owner-typed record cannot be decided. */
+    private storedOwner;
+    private ownerMismatch;
+    /** The subject's identity @id, or a denial when nobody is signed in. A signed-in subject with no identity cannot be decided. */
+    private subjectOwnerId;
+    private ownedUserContext;
+    /**
+     * Condition values (#1823). A `resource:` attribute is the value the manager
+     * read from the stored row, never a request field. Subject and environment
+     * attributes come from the PIP.
+     */
+    private ownedReader;
+    private ownedTypeResult;
+    private decisionFrom;
     categoriesGranting(action: string): string[];
 }
 export default PolicyDecisionPoint;

package/lib/src/security/PolicyInformationPoint.d.ts

@@ -138,6 +138,7 @@ export interface PageAttributes {
  * if (await pip.checkPagePermissionWithContext(wikiContext, 'edit')) { ... }
  */
 declare class PolicyInformationPoint extends BaseManager {
+    private readonly clock;
     /** Read at the moment of use: this manager starts before PolicyEvaluator (#1431 step 13). */
     private get policyEvaluator();
     /**
@@ -145,8 +146,9 @@ declare class PolicyInformationPoint extends BaseManager {
      *
      * @constructor
      * @param {WikiEngine} engine - The wiki engine instance
+     * @param {() => Date} [clock] - The time `environment:` attributes are read at; injectable for tests
      */
-    constructor(engine: WikiEngine);
+    constructor(engine: WikiEngine, clock?: () => Date);
     /**
      * Initializes the PolicyInformationPoint by loading policies and configurations
      *
@@ -543,6 +545,23 @@ declare class PolicyInformationPoint extends BaseManager {
      * evaluator awaits every read).
      */
     subjectAttribute(subject: SubjectFacts | null | undefined, name: string): unknown;
+    /**
+     * An environment attribute a condition reads (#2261): `environment:<name>`,
+     * declared in `ngdpbase.access.environment-attributes` and read from its
+     * `from` source here, the only place one is read. `schedule:<name>` is whether
+     * that schedule in `ngdpbase.schedules` is open at `now`; `config:<key>` is
+     * the boolean stored at that configuration key, any key, secrets included.
+     * Missing when it is not declared, the schedule is absent, the stored value is
+     * not a boolean, or the read fails; the evaluator then fails closed. The value
+     * is returned to the evaluator and goes nowhere else: it is never logged.
+     */
+    environmentAttribute(name: string, now?: Date): boolean | undefined;
+    /**
+     * A reader of environment attributes for one decision or one listing
+     * (#2261): the clock is read once, on the first attribute asked for, and
+     * each attribute once, so every policy and every page sees one instant.
+     */
+    environmentReader(): (name: string) => unknown;
     /** One read of a declared subject attribute from its source. A value of the wrong type, or a source that throws, is missing. */
     private readSubjectSource;
     /** The page's category for the policies (#2255): lowercased; the default when it has none; `shared` in a shared folder. */
@@ -581,6 +600,13 @@ declare class PolicyInformationPoint extends BaseManager {
      * nothing. Same record as every other page denial, `policyIds` included.
      */
     recordPageRefusal(subject: UserContext | null | undefined, pageName: string, action: string, reason: string, policyIds?: readonly string[], conditionNotMet?: readonly string[]): Promise<void>;
+    /**
+     * Record a write the signed-out write gate refused before any route ran
+     * (#2298). The resource is the route as asked (`POST /save/Home`): method
+     * and path, never the query or the body, which can carry a password or a
+     * token. Standard tier and best-effort, like every other denial.
+     */
+    recordRouteRefusal(subject: UserContext | null | undefined, route: string): Promise<void>;
     /** The name a decision is recorded under: the subject's, or `anonymous`. */
     private static recordedUser;
     /**

package/lib/src/security/ownedRecords.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Add-on record decisions (#1823).
+ *
+ * The add-on's manager is the enforcement point. It reads `owner` from the
+ * stored row and asks {@link PolicyDecisionPoint.decideOwnedRecord} or
+ * {@link PolicyDecisionPoint.decideOwnedList}. The answer is never null.
+ * A type that declares `owner` (an identity @id) is refused to anyone but
+ * that owner: under a proxy grant the subject is the person represented, so
+ * the delegate is allowed and a role is not. A type with no `owner` is
+ * decided by policy alone. A list that is refused is a denial, not an empty
+ * page of rows.
+ */
+/** The PDP cannot decide. The caller fails closed; this is not a deny. */
+export declare class OwnedRecordError extends Error {
+    constructor(message: string);
+}
+/** One record, with the attributes the manager read from its stored row. */
+export interface OwnedRecordAsk {
+    action: string;
+    resource: {
+        type: string;
+        id: string;
+        /** From the stored row. `owner`, when the type declares it, is the identity @id. */
+        attributes?: Record<string, unknown>;
+    };
+}
+/** A list of one type. There is no owner argument: the filter comes from the subject. */
+export interface OwnedListAsk {
+    action: string;
+    resource: {
+        type: string;
+    };
+}
+/**
+ * A constraint the manager turns into a bound parameter. Never SQL.
+ * `equals` means the column must equal the one value.
+ */
+export interface OwnedRecordFilter {
+    attribute: string;
+    operator: 'equals';
+    values: readonly string[];
+}
+/**
+ * The resource a refusal is audited against (#1823). `owner` is the identity
+ * @id from the stored row, `ownerUser` that person's username. Both come from
+ * storage, never from the request body.
+ */
+export interface OwnedAuditResource {
+    type: string;
+    id?: string;
+    owner?: string;
+    ownerUser?: string;
+}
+/** An explicit list answer (#1823). `filter` is empty only when the type has no owner. */
+export type OwnedListDecision = {
+    decision: 'allow';
+    filter: readonly OwnedRecordFilter[];
+} | {
+    decision: 'deny';
+    reason: string;
+    policyIds: readonly string[];
+};
+/**
+ * What is wrong with a resource type's `owner` declaration, or null (#1823).
+ * `owner`, when present at all, must be exactly `{ "type": "identity" }`.
+ * Anything else, `null` included, would quietly make an owner type
+ * policy-alone, so the decision throws and start-up refuses the config.
+ */
+export declare function ownerDeclarationProblem(type: string, entry: unknown): string | null;

package/lib/src/security/signedOutWrites.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The signed-out write list (#2298): the one place that names which routes may
+ * be written to by someone who is not signed in.
+ *
+ * Every request from a caller who is not signed in, other than GET, HEAD and
+ * OPTIONS, is refused by `signedOutWriteGate` (src/middleware/signedOutWriteGate.ts),
+ * before any route runs, unless the route is on this list. A new write route
+ * is therefore closed to signed-out callers until someone adds it here with a
+ * reason, which is the point (#2294 came from routes that were open until
+ * their author remembered to close them).
+ *
+ * What belongs here: a route a person reaches BEFORE they are signed in (the
+ * steps of signing in, registering, recovering a password, accepting an
+ * invitation), a link followed from an email in any browser, and a public form.
+ * What does not: anything that asks for a permission a signed-out caller
+ * never holds. A route that answers its own token (a Bearer token, which the
+ * gate counts as signed in) needs no entry.
+ *
+ * Core's routes are listed below. An add-on lists its own through the add-on
+ * host, `host.allowSignedOutWrite(...)`, which accepts only a route under the
+ * add-on's own `/api/<slug>/` or `/addons/<slug>/`, and refuses a slug that
+ * names one of core's own `/api/` or `/addons/` prefixes. Those are the only
+ * ways onto the list, and it is sealed once the add-ons have loaded; outside
+ * tests (`NODE_ENV=test`) the seal cannot be undone.
+ *
+ * Permission to write is still asked by each route, as always: an entry only
+ * lets the request reach the route, it grants nothing.
+ */
+export type WriteMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface SignedOutWriteRoute {
+    method: WriteMethod;
+    /** An Express path: literal segments and `:name` parameters only. */
+    path: string;
+    /** Why a caller who is not signed in must reach it. Required. */
+    reason: string;
+}
+/** Whether the method may change things, and so is held by the gate: anything but GET, HEAD and OPTIONS. */
+export declare function isWriteMethod(method: string): boolean;
+/**
+ * Slugs an add-on may not use to list a route, because core already answers
+ * under `/api/<slug>/` or `/addons/<slug>/`: an add-on in a directory named
+ * `admin` must not open `/api/admin/...`. Kept in step with core's route
+ * files; `signedOutWriteGate.test.ts` checks it against the route inventory.
+ */
+export declare const RESERVED_ADDON_SLUGS: ReadonlySet<string>;
+/**
+ * Core's list. Each reason says why the route cannot wait for a sign-in.
+ * Routes that need a signed-in session by their nature (consent, the
+ * account-setup password, the second-factor enrolment, reauthentication) are
+ * not here: their callers are signed in when they reach them.
+ */
+export declare const CORE_SIGNED_OUT_WRITES: readonly SignedOutWriteRoute[];
+/**
+ * An add-on's declaration of a route a signed-out caller may write to.
+ * Called through `AddonHost.allowSignedOutWrite`, bound to the add-on's slug.
+ * Throws on anything outside the add-on's own paths, so one add-on can never
+ * open another's, or core's.
+ */
+export declare function declareAddonSignedOutWrite(slug: string, route: SignedOutWriteRoute): void;
+/** Close the list to add-ons. Called once, after they have loaded. */
+export declare function sealSignedOutWrites(): void;
+/** Test support: forget add-on declarations and reopen the list. Refuses outside `NODE_ENV=test`, so a sealed list stays sealed. */
+export declare function resetSignedOutWrites(): void;
+/** Every route on the list, core's then the add-ons'. */
+export declare function signedOutWriteRoutes(): Array<SignedOutWriteRoute & {
+    owner: string;
+}>;
+/** The reason the route is on the list, or null when a signed-out caller may not write to it. */
+export declare function signedOutWriteReason(method: string, path: string): string | null;