@jwilleke/ngdpbase-types 5.42.0 → 5.43.0

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

@@ -30,6 +30,8 @@ import { type RoleGrant } from '../utils/roleGrants.js';
 import { type ActorContext } from '../context/ActorContext.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). */
+export declare const VAULTS_ADMIN_ACCESS_KEY = "ngdpbase.vaults.admin-access";
 /**
  * What `decide`, `permits` and `holds` take (#2022): the caller's own context
  * — a request's `PermissionSubject` or a job's `JobContext` — or a subject
@@ -256,7 +258,20 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * own sign-in, once policy has said yes.
      */
     private proxyCeiling;
-    /** Does the named actor HOLD `action` (policy alone, live)? Step-up is the proxy subject's question, not theirs. */
+    /**
+     * Does the named actor HOLD the action (policy alone, live)? Step-up is the
+     * proxy subject's question, not theirs. Asked about the same page when the
+     * request names one (#2255), so an actor who may edit only some categories
+     * is asked about this page's.
+     *
+     * Inside a vault or a shared folder the actor is asked the bare capability,
+     * as before #2255 (#2267): the `vault` and `shared-folder` matchers assume
+     * the container rule proved the subject may be there, and for the actor it
+     * did not — the person represented passed it. Asked with the container, a
+     * reader actor would hold everything `vault-owner` holds in someone else's
+     * vault. The door (`permitsInVault`), the page door and the list filter all
+     * come through here, so they agree.
+     */
     private actorHolds;
     /**
      * Decide. The order is load-bearing:
@@ -277,5 +292,46 @@ export declare class PolicyDecisionPoint extends BaseManager {
     decide(subject: DecisionInput, request: DecisionRequest): Promise<Decision>;
     /** `decide`, with the step-up rule applied or not — {@link holds} is the only caller that leaves it out. */
     private evaluate;
+    /**
+     * The first declared system category on which the policies permit a page
+     * write (#2255, decision 10), or null. Asked once per category, so a deny
+     * on one still wins there. Owner conditions are unknown here (no page), so
+     * a grant that needs the author does not count. Only enabled categories
+     * that are not bound to a location count (#2268): `shared` is a shared
+     * folder's, decided with the folder, and every account holds `vault-owner`,
+     * so counting it would give a reader every page write as a capability.
+     */
+    private onSomeCategory;
+    /**
+     * Every system category the catalogue declares, core and add-ons, enabled
+     * or not, lowercased; with `inUse`, only those enabled and not bound to a
+     * shared folder (`storageLocation.sharedfolder`).
+     */
+    private declaredCategories;
+    /**
+     * May an administrator enter `owner`'s vault (#2255,
+     * `ngdpbase.vaults.admin-access`)? Asked only after the container rule has
+     * refused someone who is not the owner. Yes when all hold:
+     *
+     * - the key is true, read now, on every request (shipped true);
+     * - the caller is a signed-in session or a job, not a share link, a proxy
+     *   or an agent token;
+     * - the caller holds `admin-system`;
+     * - the vault is not encrypted: an encrypted vault always needs its key,
+     *   whatever the key says, so it is not entered at all.
+     *
+     * `record` true (a door) writes `vault-admin-access` with the administrator
+     * as the actor and the owner, vault and page named; an affordance passes
+     * false and records nothing. Lists and search never ask this, so an
+     * administrator does not see other people's vault pages listed.
+     */
+    adminMayEnterVault(ctx: ActorContext | null | undefined, owner: string, vault: string, resource: string, record?: boolean): Promise<boolean>;
+    /**
+     * The declared system categories on which an allow policy grants `action`
+     * through the `system-category` resource type (#2255). The sitemap asks it
+     * with `pushed-pages-edit` to leave pushed pages out. A summary of the
+     * policies, never an answer to "may this subject".
+     */
+    categoriesGranting(action: string): string[];
 }
 export default PolicyDecisionPoint;

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

@@ -1,4 +1,5 @@
 import BaseManager from '../managers/BaseManager.js';
+import { type AalFacts } from '../utils/policyAttributes.js';
 import { type ActorContext } from '../context/ActorContext.js';
 import { WikiEngine } from '../types/WikiEngine.js';
 import type { AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
@@ -52,6 +53,10 @@ interface UserContext {
  * form. They convert it themselves, through {@link asSubject}.
  */
 type PageQuestionCaller = ActorContext | UserContext | null | undefined;
+/** What a subject attribute is read from (#2261): who, and what bears on `subject:aal`. */
+export type SubjectFacts = AalFacts & {
+    username?: string;
+};
 /**
  * Access decision log entry
  */
@@ -61,8 +66,24 @@ interface AccessDecisionLog {
     action?: string;
     allowed?: boolean;
     reason?: string;
+    /** The policies that decided (#2255), recorded on a denial. */
+    policyIds?: string[];
+    /** Allows that matched but whose condition was not met (#2288), recorded on a denial. */
+    conditionNotMet?: string[];
     context?: Record<string, unknown>;
 }
+/**
+ * What the policies may read about a page (#2255), resolved by the PIP from
+ * the page itself. `attributes` holds what a resource type matches on
+ * (`system-category`), read eagerly; `read` answers a condition's
+ * `resource:<name>` for an attribute declared on the `page` resource type,
+ * lazily, so a lookup (the owner's account) is made only when a policy needs
+ * it. `undefined` is a missing attribute.
+ */
+export interface PageAttributes {
+    attributes: Record<string, unknown>;
+    read(name: string): unknown;
+}
 /**
  * PolicyInformationPoint — what a page decision needs to know about the page
  * (#1431; was ACLManager until step 8).
@@ -353,10 +374,12 @@ declare class PolicyInformationPoint extends BaseManager {
      *   Tier 1 is skipped for a vault page: `audience` grants nothing there.
      * - __Tier 0.5, author-lock__, `edit` only. It only denies: an author, or a
      *   subject holding `admin-system` (#1431 7b), falls through to Tier 1+.
-     * - __Tier 1, frontmatter__ `access[action]` / `audience`. Page-level, and
-     *   overrides global policy when it states a rule (#1054). An `audience`
-     *   covers every action, and a subject holding `admin-system` is its one
-     *   exception; `access` has none (#1964).
+     * - __Tier 1, frontmatter__ `audience`. Page-level, and decides a view
+     *   when it states a rule (#1054). An `audience` covers every action, and a
+     *   subject holding `admin-system` is its one exception (#1964). `access`
+     *   is no longer read (#2255).
+     * - A page in a shared folder is decided by the folder's permission, and a
+     *   change also by the `shared` category's policy and author-lock (#2255).
      * - __Tier 2.__ For a share visitor the share IS the policy (#1222); for
      *   anyone else, global policy.
      * - __Default deny.__ Nothing below Tier 2 grants — JSPWiki's page-body ACL
@@ -477,14 +500,65 @@ declare class PolicyInformationPoint extends BaseManager {
      */
     canUserAccessMediaItem(caller: PageQuestionCaller, item: MediaItem): Promise<boolean>;
     /**
-     * Check front matter audience / access fields (Tier 1).
+     * Check the front matter audience (Tier 1).
      * Returns a decision object; decided=false means no front matter restriction — fall through.
      *
      * An audience that leaves the subject out refuses every action, unless the
      * subject holds `admin-system` (#1964, operator 2026-10-23): asked only
-     * then. `access[action]` has no such exception.
+     * then. `access` is no longer read (#2255).
      */
     private checkFrontmatterAccess;
+    /**
+     * A page's attributes for the policies (#2255, XACML's PIP): the PDP asks
+     * this from the page id, so no route passes them. `knownMetadata` is the
+     * frontmatter when this PIP already holds it (the page door); otherwise the
+     * page is read with the caller's own context, so a sealed page stays closed
+     * to anyone without its key (#1422). A page that cannot be read has no
+     * attributes: no category policy matches it and every condition on it is
+     * unknown.
+     */
+    pageAttributes(caller: PageQuestionCaller, pageName: string, knownMetadata?: Record<string, unknown> | null): Promise<PageAttributes>;
+    /**
+     * {@link pageAttributes} from frontmatter already in hand (the list
+     * filter). Attributes are those declared on the `page` resource type in
+     * `ngdpbase.access.resource-types`, each read from its `from` source; the
+     * sources are code (`frontmatter:<field>` today).
+     *
+     * - `system-category` is lowercased; a page with none is in the default
+     *   category (the entry with `default: true`); a page in a shared folder is
+     *   `shared`, whatever its frontmatter says (#2255).
+     * - An `identity` attribute (`owner`, from `author`) is compared by the
+     *   account it names: an @id or a username not yet converted both read as
+     *   that account's username, an orphan as missing (#2097).
+     */
+    pageAttributesFrom(pageName: string, metadata: PageFrontmatter | null | undefined): PageAttributes;
+    /**
+     * A subject attribute a condition reads (#2255, #2261): `subject:<name>`,
+     * declared in `ngdpbase.access.subject-attributes` (`id` always is) and read
+     * from its `from` source here, the only place a subject attribute is read. A
+     * request cannot send one. Missing when it is not declared, cannot be read, or
+     * the subject has none (`subject:aal` of a visitor who is not signed in, of a
+     * token made before it was stored); the evaluator then fails closed. Returns
+     * the value, or a Promise of it for a field read from the account (the
+     * evaluator awaits every read).
+     */
+    subjectAttribute(subject: SubjectFacts | null | undefined, 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. */
+    private pageCategory;
+    /** The attributes declared on the `page` resource type (#2255). */
+    private declaredPageAttributes;
+    /** An identity reference as the policies compare it: the username of the account it names, or missing (#2097). */
+    private identityValue;
+    /** Pages already warned about for an `access:` that is not the legacy stamp (#2255): once per page per process. */
+    private readonly warnedAccess;
+    /**
+     * `access:` frontmatter no longer has any effect (#2255). The stamp install
+     * wrote (`{ edit: [admin] }`) is left alone silently; any other value is
+     * someone's rule that is now ignored, so it is said once per page.
+     */
+    private warnLegacyAccess;
     /**
      * Does the page's `audience` admit this subject (#1964)? True when the page
      * names no audience, the subject matches it, or the subject holds
@@ -501,6 +575,12 @@ declare class PolicyInformationPoint extends BaseManager {
      * Accepts either a single object or positional args for backward compatibility.
      */
     logAccessDecision(userOrObj: UserContext | AccessDecisionLog, pageName?: string, action?: string, allowed?: boolean, reason?: string, _context?: Record<string, unknown>): void;
+    /**
+     * Record a page write a door refused on a capability alone (#2272): the
+     * route's `page-edit` / `page-create` check asks the PDP, which records
+     * 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>;
     /** The name a decision is recorded under: the subject's, or `anonymous`. */
     private static recordedUser;
     /**

package/lib/src/security/permissions.generated.d.ts

@@ -30,6 +30,8 @@ export type CorePermission =
  | 'identity-read'
 /** Browse and view the media library (not delegated to anonymous visitors) */
  | 'media-read'
+/** Set or change a page's system-category (#2255). A page created in a shared folder gets the shared category without it */
+ | 'page-categorize'
 /** Create new pages */
  | 'page-create'
 /** Delete pages */
@@ -50,6 +52,12 @@ export type CorePermission =
  | 'profile-manage'
 /** Let another person act for you, within permissions you hold, and revoke it (#1762). Every signed-in role except demo-admin; an administrator making or revoking a grant for someone else also needs user-edit, and that grant never carries a copy of the person's vault key. A grant that includes proxy-grant lets the proxy give others access too. Asks for a fresh sign-in */
  | 'proxy-grant'
+/** Delete pushed pages (#2255) */
+ | 'pushed-pages-delete'
+/** Edit pushed pages: pages shipped by the system or an add-on (the categories a policy grants it on; system, documentation and addon as shipped) (#2255) */
+ | 'pushed-pages-edit'
+/** Rename pushed pages (#2255) */
+ | 'pushed-pages-rename'
 /** Search pages */
  | 'search-page'
 /** Search users */

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

@@ -95,13 +95,6 @@ export interface PageFrontmatter {
      * in Slice E (v3.7.0). All datasets migrated; this field is the only source of truth.
      */
     private?: boolean;
-    /** Per-action principal lists — overrides audience for the named action */
-    access?: {
-        view?: string[];
-        edit?: string[];
-        delete?: string[];
-        [key: string]: string[] | undefined;
-    };
     /** Additional custom metadata */
     [key: string]: unknown;
 }

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

@@ -12,11 +12,12 @@
  * again because a `.d.ts` may not import a `.ts`. Four copies of one shape is
  * how a field gets added to one and missed in the others.
  */
-/** Who a policy grants to. The evaluator matches `role` and `job` (#1999), its `SUBJECT_MATCHERS`. */
+/** Who a policy grants to. The evaluator matches `role`, `job` (#1999), `authenticated` and `anyone` (#2261), its `SUBJECT_MATCHERS`. */
 export interface PolicySubject {
-    /** `role`, or `job` for a scheduled job acting as itself (#1999). */
+    /** `role`, `job` for a scheduled job acting as itself (#1999), or `authenticated` / `anyone` (#2261). */
     type: string;
-    value: string;
+    /** The role or the job id. `authenticated` and `anyone` take none. */
+    value?: string;
 }
 /**
  * What a policy covers.
@@ -28,6 +29,45 @@ export interface PolicyResource {
     type: string;
     pattern: string;
 }
+/**
+ * A comparison of one attribute with a value (#2255, #2261). A string starting
+ * `subject:`, `resource:` or `environment:` names an attribute; anything else
+ * is a literal. Exactly one operator key beside `attribute`:
+ * `equals`, `not-equals`, `in`, `greater-or-equal`, `less-or-equal`.
+ */
+export type LeafCondition = {
+    attribute: string;
+} & ({
+    equals: unknown;
+} | {
+    'not-equals': unknown;
+} | {
+    in: unknown[] | string;
+} | {
+    'greater-or-equal': number | string;
+} | {
+    'less-or-equal': number | string;
+});
+/**
+ * A policy's condition: a {@link LeafCondition}, or `any-of` / `all-of` /
+ * `not` over other conditions, nested at most 4 deep.
+ *
+ * Each node is true, false or unknown. A leaf reading an attribute that is
+ * missing is unknown; in `any-of` a true branch decides, in `all-of` a false
+ * one does, and `not` of unknown is unknown. An allow applies only when the
+ * condition is true; a deny applies when it is true or unknown.
+ */
+export type PolicyCondition = LeafCondition | {
+    'any-of': PolicyCondition[];
+} | {
+    'all-of': PolicyCondition[];
+} | {
+    not: PolicyCondition;
+};
+/** The prefixes that mark a condition value as an attribute rather than a literal (#2255). */
+export declare const ATTRIBUTE_CATEGORIES: readonly ["subject", "resource", "environment"];
+/** True when `value` names an attribute (`subject:id`, `resource:owner`), not a literal. */
+export declare function isAttributeName(value: unknown): value is string;
 /** One entry of `ngdpbase.access.policies`. */
 export interface Policy {
     id: string;
@@ -44,6 +84,8 @@ export interface Policy {
     subjects?: PolicySubject[];
     resources?: PolicyResource[];
     actions?: string[];
+    /** Applies only when this holds (#2255); see {@link PolicyCondition}. */
+    condition?: PolicyCondition;
     [key: string]: unknown;
 }
 /**
@@ -88,11 +130,18 @@ export interface DecisionRequest {
     action: string;
     resource?: DecisionResource;
     /**
-     * What the PIP knows about the resource beyond its reference, for the
-     * policy resource types that match on it (#1504): a page's
-     * `system-category`. The PDP passes it through; it never loads it.
+     * Where a page or file sits, for the resource types that match on it: the
+     * `vault` (#1539) or the `shared-folder` (#2125). A page's own attributes —
+     * its `system-category`, its `owner` — are never passed: the PDP asks the
+     * PIP for them from the page id (#2255).
      */
     attributes?: Record<string, unknown>;
+    /**
+     * The page's frontmatter when the PIP itself already holds it (the page
+     * door, the list filter), so the PDP's lookup reads no page twice. Only the
+     * PIP sets it; a route never does (#2255).
+     */
+    pageMetadata?: Record<string, unknown> | null;
     /**
      * Whether a share's `resources` cover the thing being asked about.
      *
@@ -128,6 +177,18 @@ export interface Decision {
      */
     applicable: boolean;
     reason: string;
+    /**
+     * The ids of the policies that decided (#2255): the denies that matched,
+     * or, when none did, the allows that matched. Empty when no policy matched
+     * or something other than policy decided (a ceiling, step-up).
+     */
+    policyIds: string[];
+    /**
+     * The ids of allow policies that matched subject, resource and action but
+     * whose condition was false or unknown (#2288), so a refusal can say which
+     * allow was not met. Ids only, never attribute values. Absent when none.
+     */
+    conditionNotMet?: string[];
 }
 /**
  * The reason a deny carries when the subject holds the permission but its

package/lib/src/types/Policy.js

@@ -1,4 +1,10 @@
 'use strict';
+/** The prefixes that mark a condition value as an attribute rather than a literal (#2255). */
+export const ATTRIBUTE_CATEGORIES = ['subject', 'resource', 'environment'];
+/** True when `value` names an attribute (`subject:id`, `resource:owner`), not a literal. */
+export function isAttributeName(value) {
+    return typeof value === 'string' && ATTRIBUTE_CATEGORIES.some((c) => value.startsWith(`${c}:`));
+}
 /**
  * The reason a deny carries when the subject holds the permission but its
  * sign-in is not fresh enough to act (#1635). Declared once: the PDP writes it

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

@@ -319,6 +319,18 @@ export interface PageProvider extends BaseProvider {
         reason: string;
         detail?: string;
     }>;
+    /**
+     * Where a trashed page would come back to, and its frontmatter, so the
+     * write door can decide the restore before it happens (#1815, security
+     * review L5): its title, or its vault name when it was deleted from a
+     * vault. Null when the uuid is not in the trash.
+     *
+     * @param uuid - Page UUID
+     */
+    deletedPageForRestore?(uuid: string): Promise<{
+        name: string;
+        metadata: PageFrontmatter;
+    } | null>;
     /**
      * Get all page titles
      * @returns Sorted array of page titles

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

@@ -56,6 +56,12 @@ export interface UserPreferences {
     /** Additional custom preferences */
     [key: string]: unknown;
 }
+/**
+ * The account fields whose change is recorded on `user-edit` with the field name
+ * only, and that a policy condition may never read as `account:` or `profile:`
+ * (#2261): the password, the email, the roles and the like.
+ */
+export declare const SENSITIVE_USER_FIELDS: readonly ["password", "roles", "isActive", "isExternal", "isTest", "email", "profileLocked", "username"];
 /**
  * User object
  *

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

@@ -55,15 +55,3 @@ export interface SyncRowState {
  * @param userModifiedFlag - The live copy is explicitly marked edited
  */
 export declare function syncRowState(seedStatus: SeededAddonPageStatus, userModifiedFlag?: boolean): SyncRowState;
-/**
- * Default edit access for a page ngdpbase ships (#971, #1411): a `general`
- * page is instance-owned and gets no stamp; any other category — system,
- * documentation, addon, unclassified — is administrator-edit only. A source
- * that declares its own `access` overrides this.
- *
- * @param category - The page's resolved `system-category`
- * @returns The access object to stamp, or undefined to leave the page unprotected
- */
-export declare function defaultShippedPageAccess(category: unknown): {
-    edit: string[];
-} | undefined;

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

@@ -224,6 +224,8 @@ export declare const AUDIT_EVENT: {
     readonly USER_EDIT: "user-edit";
     /** User profile read; not recorded, read volume */
     readonly USER_READ: "user-read";
+    /** An administrator read or changed a page inside another person's vault that is not encrypted (ngdpbase.vaults.admin-access, #2255): the administrator is the actor, and the vault's owner, the vault and the page are named */
+    readonly VAULT_ADMIN_ACCESS: "vault-admin-access";
     /** Not an action: read from a proxy grant at the vault door; the grant itself is recorded as proxy-grant */
     readonly VAULT_PROXY: "vault-proxy";
     /** A vault page's leftovers moved into its vault (#1842): its shared-pool files (moved, or copied where other public pages use them) and its footnotes and comments from the public folders. Names the owner, vault and page uuid and the counts, never a title or file name. Run by the vault's owner, or for a vault that isn't sealed by someone holding admin-system */

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

@@ -231,6 +231,8 @@ export const AUDIT_EVENT = {
     USER_EDIT: 'user-edit',
     /** User profile read; not recorded, read volume */
     USER_READ: 'user-read',
+    /** An administrator read or changed a page inside another person's vault that is not encrypted (ngdpbase.vaults.admin-access, #2255): the administrator is the actor, and the vault's owner, the vault and the page are named */
+    VAULT_ADMIN_ACCESS: 'vault-admin-access',
     /** Not an action: read from a proxy grant at the vault door; the grant itself is recorded as proxy-grant */
     VAULT_PROXY: 'vault-proxy',
     /** A vault page's leftovers moved into its vault (#1842): its shared-pool files (moved, or copied where other public pages use them) and its footnotes and comments from the public folders. Names the owner, vault and page uuid and the counts, never a title or file name. Run by the vault's owner, or for a vault that isn't sealed by someone holding admin-system */

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

@@ -142,6 +142,8 @@ export interface TokenInput extends CommonInput {
     previousExpiresAt?: string;
     /** Only meaningful for `revoke`; ignored otherwise. */
     revokedBy?: string;
+    /** Only meaningful for `mint` (#2287): the sign-in level stored with the token; absent when it stored none. */
+    aal?: 1 | 2 | 3;
 }
 /**
  * What an attachment record says about the file. A file in an ENCRYPTED store

package/lib/src/utils/auditEvents.js

@@ -289,7 +289,7 @@ export async function recordAuditEvent(sink, event, onError) {
  * every event is useless as a filter.
  */
 export function buildTokenAuditEvent(input) {
-    const { op, id, owner, ownerUser, name, scopes, expiresAt, previousExpiresAt, revokedBy, viaToken } = input;
+    const { op, id, owner, ownerUser, name, scopes, expiresAt, previousExpiresAt, revokedBy, viaToken, aal } = input;
     const who = whoOf(input);
     const metadata = {
         id,
@@ -302,6 +302,8 @@ export function buildTokenAuditEvent(input) {
     if (op === 'mint') {
         metadata.scopes = [...(scopes ?? [])];
         metadata.expiresAt = expiresAt;
+        // #2287: the level the token holds, or null when it stored none; the record that answers "was this minted after a second factor?"
+        metadata.aal = aal ?? null;
     }
     if (op === 'extend') {
         metadata.previousExpiresAt = previousExpiresAt;

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

@@ -1,9 +1,11 @@
 /**
  * frontmatterAccess — the single implementation of ACL Tier 1 (#1054).
  *
- * A page's frontmatter can restrict who may act on it, via `access[<action>]`
- * or `audience`, which covers every action (#1964). Two subsystems needed
- * that answer and each had its own version of it, which is how they came to disagree:
+ * A page's frontmatter can restrict who may act on it with `audience`, which
+ * covers every action (#1964). The `access[<action>]` lists it once honoured
+ * were removed in #2255: what a user may do on a page is decided by its
+ * system-category and policy. Two subsystems needed the audience answer and
+ * each had its own version of it, which is how they came to disagree:
  *
  *   - `PolicyInformationPoint.checkFrontmatterAccess` decided a request, correctly.
  *   - `VersioningFileProvider.getRecentChanges` decided a listing, and only
@@ -20,8 +22,6 @@
  */
 /** The frontmatter fields Tier 1 reads. */
 export interface AccessMetadataLike {
-    /** `{ view: ['role'], edit: [...] }` — per-action principal lists. */
-    access?: unknown;
     /** Who may act on the page at all; administrators excepted (#1964). */
     audience?: unknown;
 }
@@ -39,11 +39,6 @@ export interface FrontmatterDecision {
  * neither read nor edit the page.
  */
 export declare function audiencePrincipals(metadata: AccessMetadataLike | null | undefined): string[] | null;
-/**
- * The page's `access[action]` list, or null when it states none. It applies
- * to that action only, and to everyone — administrators included.
- */
-export declare function accessPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
 /**
  * The entry `addon:<slug>` (#1964): "people who turned on the per-person
  * add-on <slug>". It is matched only against the viewer's enabled add-ons,
@@ -54,11 +49,10 @@ export declare const ADDON_PRINCIPAL_PREFIX = "addon:";
  * Whether deciding `action` on this page needs the viewer's enabled add-ons —
  * so a caller asks for them only when the page names one (#1964).
  */
-export declare function namesAddonPrincipal(metadata: AccessMetadataLike | null | undefined, action: string): boolean;
+export declare function namesAddonPrincipal(metadata: AccessMetadataLike | null | undefined, _action: string): boolean;
 /**
- * Every add-on slug the page names in `audience` or in any `access` list, once
- * each, in the order first named — for the warning about a slug that can match
- * nobody (#1964).
+ * Every add-on slug the page names in `audience`, once each, in the order
+ * first named — for the warning about a slug that can match nobody (#1964).
  */
 export declare function addonAudienceSlugs(metadata: AccessMetadataLike | null | undefined): string[];
 /**
@@ -75,16 +69,13 @@ export declare const AUDIENCE_ADMIN_MATCH = "admin-system";
  * plus their username. Callers holding a `UserContext` should pass
  * `[...roles, username]`; the provider layer already works in these terms.
  *
- * Two rules, in order (#1964, operator 2026-10-23):
- *
- * - __`audience`__ applies to every action. Someone it leaves out may neither
- *   read nor edit the page: every action is refused. The one exception is an
- *   administrator — a viewer holding `admin-system`, which the caller decides
- *   and passes as `isAdmin` (this module never reads a role for it). For
- *   `view`, a viewer the audience admits is allowed; for any other action it
- *   only lets them through to `access` and then policy.
- * - __`access[action]`__ applies to that action, to everyone, administrators
- *   included. When the page states it, it decides.
+ * `audience` applies to every action (#1964, operator 2026-10-23). Someone it
+ * leaves out may neither read nor edit the page: every action is refused. The
+ * one exception is an administrator — a viewer holding `admin-system`, which
+ * the caller decides and passes as `isAdmin` (this module never reads a role
+ * for it). For `view`, a viewer the audience admits is allowed; for any other
+ * action it only lets them through to policy. A page's `access` field is not
+ * read (#2255).
  *
  * An `addon:<slug>` entry matches only when `<slug>` is in `enabledAddons`,
  * the viewer's enabled per-person add-ons (#1964); a caller that does not

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

@@ -0,0 +1,16 @@
+/** One leftover key and what to tell the operator about it. */
+export interface LegacyStoreKey {
+    key: string;
+    kind: string;
+    setting: 'owner' | 'encrypt';
+    /** One sentence: the key, that it has no effect, and what replaces it. */
+    message: string;
+}
+/**
+ * Every legacy per-kind key in the operator's custom config, in file order.
+ * `categories` is the merged `ngdpbase.system-category` map, used to name the
+ * entry that declares the kind's vault (the `default` vault is `general`'s).
+ */
+export declare function legacyStoreKeys(customConfig: Record<string, unknown> | null | undefined, categories: unknown): LegacyStoreKey[];
+/** The needs-attention reason for a non-empty list: every key, in one sentence. */
+export declare function legacyStoreKeysReason(found: LegacyStoreKey[]): string;

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

@@ -0,0 +1,55 @@
+/**
+ * The page-write policies after #2255, and the migration of a site's stored
+ * copies of the old ones.
+ *
+ * Until #2255 the shipped role policies granted `page-edit`, `page-delete` and
+ * `page-rename` on every page (`page: *`), and an `access: { edit: [admin] }`
+ * stamp on each shipped page was the only thing keeping editors out of the
+ * system and documentation pages. Those grants now sit on the
+ * `system-category` resource type, one policy per group of categories, and the
+ * stamp is gone.
+ *
+ * A site that ever saved `ngdpbase.access.policies` (the configuration editor,
+ * the Shared folders screen) holds a full copy of the old role policies, and a
+ * stored entry replaces the shipped one with the same id whole
+ * (`src/utils/configFiles.ts`). Its `page-edit` on `page: *` would reopen every
+ * pushed page to editors. So, before the merge, in memory:
+ *
+ * - a stored entry with a shipped id below loses the page writes it held on
+ *   `page: *`; any it held that the shipped category policies do not give that
+ *   role is kept, on the general category only, as a new policy
+ *   `<id>-page-write`;
+ * - every other policy that grants a page write on a `page` resource to a role
+ *   other than admin, and every deny policy (a deny now overrides an allow
+ *   whatever its priority), is reported and left as it is: it is the site's
+ *   own choice.
+ *
+ * Pure: the caller logs and reports. The site's file is not rewritten; saving
+ * the policy list from the configuration editor writes the migrated list.
+ */
+import type { Policy } from '../types/Policy.js';
+/** What the migration did and found, one sentence each. */
+export interface PageWritePolicyReport {
+    /** Stored shipped policies rewritten in memory. */
+    rewritten: string[];
+    /** Policies left alone that now decide differently, or reopen pushed pages. */
+    review: string[];
+}
+/**
+ * Rewrite the stored copies of the moved shipped policies, in `policies` (the
+ * custom layer's `ngdpbase.access.policies`), and return what was done and
+ * what an administrator should review. Returns the list to store in place of
+ * the input; the input is not changed.
+ */
+export declare function migrateStoredPageWritePolicies(policies: unknown): {
+    policies: unknown;
+    report: PageWritePolicyReport;
+};
+/**
+ * Policies in force that an administrator should review after #2255: an
+ * allow that grants a page write on a `page` resource to a role other than
+ * admin (it reaches pushed pages), an allow that grants anything but
+ * page-read to `anyone` or `authenticated` (#2261, #2283), and every deny (a deny now overrides any
+ * allow, whatever the priorities).
+ */
+export declare function pageWritePoliciesToReview(policies: readonly Policy[]): string[];

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

@@ -25,6 +25,8 @@ export declare function grantablePermissions<T>(definitions: Record<string, T> |
 export declare const RETIRED_PERMISSIONS: ReadonlyMap<string, readonly string[]>;
 /** The names with every retired permission replaced by what it stood for, de-duplicated, order kept. */
 export declare function withRetiredExpanded(names: readonly string[]): string[];
+/** The names a policy may grant `action` under (#2255): a page write and its pushed-pages twin, else the action alone. */
+export declare function pageWriteAlternatives(action: string): string[];
 /**
  * What the standard OpenID Connect sign-in scopes let an app see, in plain
  * words (#1572). They are not permissions, so they are not in the catalog;