@jwilleke/ngdpbase-types 5.42.0 → 5.44.0

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,13 +29,48 @@ export interface PolicyResource {
     type: string;
     pattern: string;
 }
+/**
+ * An argument of a comparison (#2255, #2261, #2330), as XACML 3.0 writes one in
+ * lowercase. An attribute is `{ "attributeid": "subject:department-id",
+ * "datatype": "string" }`: `attributeid` starts `subject:`, `resource:` or
+ * `environment:`. A literal is `{ "value": "sales", "datatype": "string" }`,
+ * and for `X-is-in` its `value` may be an array. `datatype` is required and is
+ * one of the XACML JSON profile's short names.
+ */
+export type ConditionOperand = {
+    attributeid: string;
+    datatype: string;
+} | {
+    value: unknown;
+    datatype: string;
+};
+/**
+ * A policy's condition (#2330): one function, named for its XACML 3.0 function
+ * in lowercase, whose value is the array of its arguments.
+ *
+ * - `string-equal`, `integer-equal`, `boolean-equal`, `string-is-in`,
+ *   `integer-is-in`, `integer-greater-than`, `integer-greater-than-or-equal`,
+ *   `integer-less-than`, `integer-less-than-or-equal` take two
+ *   {@link ConditionOperand}s;
+ * - `and` and `or` take a list of conditions, `not` takes one;
+ *
+ * nested at most 4 deep.
+ *
+ * Each node is true, false or unknown. A comparison reading an attribute that
+ * is missing is unknown; in `or` a true branch decides, in `and` 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 = Record<string, Array<ConditionOperand | 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;
     name?: string;
     description?: string;
-    /** Lower runs first, so a higher-priority deny lands last and wins. */
-    priority?: number;
     /**
      * `allow` or `deny`. Typed as a string because the value comes from
      * configuration, where an operator can write anything; the evaluator treats
@@ -44,6 +80,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 +126,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 +173,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/addonConfigLayer.d.ts

@@ -128,10 +128,13 @@ export interface AddonJobPolicyLayer {
     problems: string[];
 }
 /**
- * Which jobs an addon's policies may name (#1999): its own, ids starting
- * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
- * reach the merge, so only an enabled addon is checked.
+ * An add-on's resource types (#1823). Each name starts with `<slug>-`, the
+ * same fence as its jobs and its ledger tables. `owner`, when declared, is
+ * an identity @id. A bad declaration refuses the add-on, so none of its keys
+ * merge. A turned-off add-on is not checked: its file is not merged.
  */
+export declare function addonResourceTypeProblems(slug: string, defaults: Record<string, unknown>): string[];
+export declare function addonResourceTypeLayer(addons: readonly AddonDefaults[]): AddonJobPolicyLayer;
 export declare function addonJobPolicyLayer(addons: readonly AddonDefaults[]): AddonJobPolicyLayer;
 /** The configuration key that makes an addon site-critical (#1883). */
 export declare function addonSiteCriticalKey(slug: string): string;

package/lib/src/utils/addonConfigLayer.js

@@ -316,6 +316,63 @@ export function addonSensitiveValuesLayer(addons) {
  * `<slug>.`, the prefix its job ids carry. Only an enabled addon's policies
  * reach the merge, so only an enabled addon is checked.
  */
+const RESOURCE_TYPES_KEY = 'ngdpbase.access.resource-types';
+const ATTRIBUTE_TYPES = new Set(['string', 'integer', 'boolean', 'identity', 'list']);
+/**
+ * An add-on's resource types (#1823). Each name starts with `<slug>-`, the
+ * same fence as its jobs and its ledger tables. `owner`, when declared, is
+ * an identity @id. A bad declaration refuses the add-on, so none of its keys
+ * merge. A turned-off add-on is not checked: its file is not merged.
+ */
+export function addonResourceTypeProblems(slug, defaults) {
+    const types = defaults[RESOURCE_TYPES_KEY];
+    if (types === undefined)
+        return [];
+    if (!isPlainObject(types))
+        return [`${RESOURCE_TYPES_KEY} must be an object of resource types`];
+    const problems = [];
+    const prefix = `${slug}-`;
+    for (const [name, entry] of Object.entries(types)) {
+        if (!name.startsWith(prefix) || name.length === prefix.length) {
+            problems.push(`resource type '${name}' must start with '${prefix}'`);
+            continue;
+        }
+        if (!isPlainObject(entry)) {
+            problems.push(`resource type '${name}' must be an object`);
+            continue;
+        }
+        if (entry.attributes === undefined)
+            continue;
+        if (!isPlainObject(entry.attributes)) {
+            problems.push(`resource type '${name}' attributes must be an object`);
+            continue;
+        }
+        for (const [attr, decl] of Object.entries(entry.attributes)) {
+            if (!isPlainObject(decl) || typeof decl.type !== 'string' || !ATTRIBUTE_TYPES.has(decl.type)) {
+                problems.push(`resource type '${name}' attribute '${attr}' needs a type of string, integer, boolean, identity or list`);
+                continue;
+            }
+            if (attr === 'owner' && decl.type !== 'identity') {
+                problems.push(`resource type '${name}' attribute owner must be { "type": "identity" }, the owner's identity @id`);
+            }
+        }
+    }
+    return problems;
+}
+export function addonResourceTypeLayer(addons) {
+    const layer = { refused: new Map(), problems: [] };
+    for (const addon of addons) {
+        if (!addon.enabled)
+            continue;
+        const found = addonResourceTypeProblems(addon.slug, addon.defaults);
+        if (found.length === 0)
+            continue;
+        const reason = `its resource types were refused: ${found.join('; ')}`;
+        layer.refused.set(addon.slug, reason);
+        layer.problems.push(`${addonProblemSubject(addon.slug, addon.enabled)}: ${reason}; the add-on is not loaded`);
+    }
+    return layer;
+}
 export function addonJobPolicyLayer(addons) {
     const layer = { refused: new Map(), problems: [] };
     for (const addon of addons) {
@@ -432,9 +489,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const criticalLayer = addonSiteCriticalLayer(addons, custom);
     const sensitiveLayer = addonSensitiveValuesLayer(addons);
     const jobPolicyLayer = addonJobPolicyLayer(addons);
+    const resourceTypeLayer = addonResourceTypeLayer(addons);
     const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused, ...jobPolicyLayer.refused])
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.refused, ...jobPolicyLayer.refused, ...resourceTypeLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -448,14 +506,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems, ...resourceTypeLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems], refused, databases, siteCritical };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems, ...jobPolicyLayer.problems, ...resourceTypeLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,

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

@@ -48,7 +48,10 @@ import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import type { IceReceiver, IceShim } from '../ice/types.js';
 import type { AddonReviews, ReviewHandler } from '../types/Review.js';
+import { type SignedOutWriteRoute } from '../security/signedOutWrites.js';
 import type { AddonManifest } from '../managers/AddonsManager.js';
+import type { Decision } from '../types/Policy.js';
+import type { OwnedListAsk, OwnedListDecision, OwnedRecordAsk } from '../security/ownedRecords.js';
 /** The values core offers an add-on, under the names they were imported as. */
 export interface AddonHost {
     readonly ApiContext: typeof ApiContext;
@@ -117,6 +120,28 @@ export interface AddonHost {
      * context; throw to leave the request open with your message as the reason.
      */
     readonly registerReviewHandler: (handlerId: string, handler: ReviewHandler) => void;
+    /**
+     * #2298: every request but GET, HEAD and OPTIONS from someone who is not
+     * signed in is refused before your route runs. A route that signed-out people must
+     * reach (a public form) is declared here, in `register()`, with the reason:
+     * `host.allowSignedOutWrite({ method: 'POST', path: '/api/<slug>/submit/:id', reason })`.
+     * The path must be under `/api/<slug>/` or `/addons/<slug>/` (literal
+     * segments and `:name` only), and the slug must not be one of core's own
+     * prefixes (`RESERVED_ADDON_SLUGS`), or this throws. It only lets the request reach your route: the route still asks its
+     * own permission through `ApiContext.requirePermission`.
+     */
+    readonly allowSignedOutWrite: (route: SignedOutWriteRoute) => void;
+    /**
+     * #1823: decisions for this add-on's own records. `decide` is one stored
+     * row; `list` is the filter for a list. The resource type must start with
+     * this add-on's slug. The manager reads `owner` from the row it stored and
+     * passes that, then hands a deny to `ApiContext.enforceDeny` with the
+     * resource so the refusal is audited. This records nothing itself.
+     */
+    readonly access: {
+        decide(subject: ActorContext, request: OwnedRecordAsk): Promise<Decision>;
+        list(subject: ActorContext, request: OwnedListAsk): Promise<OwnedListDecision>;
+    };
     /**
      * #1979 (ICE, D6): register an import shim, as `<slug>.<shim.name>`. Call it
      * in `register`. Refused when the manifest's `shims` does not name it.

package/lib/src/utils/addonHost.js

@@ -47,6 +47,7 @@ import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import { auditDeclarationsFrom } from './auditRegistry.js';
 import logger from './logger.js';
+import { declareAddonSignedOutWrite } from '../security/signedOutWrites.js';
 /** A host built outside a site (the test kit, with no setter given) has no account store. */
 const noPersonSwitch = () => Promise.reject(new Error('setEnabledForPerson is not available: this host was built without a site'));
 /**
@@ -121,6 +122,31 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         decide: async (ctx, id, decision, note) => reviewDoor().decide(ctx, id, decision, note)
     };
     Object.freeze(reviews);
+    const recordDoor = () => {
+        const door = engine?.getManager('PolicyDecisionPoint');
+        if (typeof door?.decideOwnedRecord !== 'function' || typeof door.decideOwnedList !== 'function') {
+            throw new Error('record access is not available: this host was built without a site\'s PolicyDecisionPoint');
+        }
+        return door;
+    };
+    const ownType = (type) => {
+        if (typeof type !== 'string' || !type.startsWith(`${slug}-`)) {
+            const message = `Add-on '${slug}' may decide only its own resource types: a type starts '${slug}-'; '${String(type)}' does not`;
+            logger.error(`[addons] ${message}`);
+            throw new Error(message);
+        }
+    };
+    const access = {
+        decide: async (subject, request) => {
+            ownType(request?.resource?.type);
+            return recordDoor().decideOwnedRecord(subject, request);
+        },
+        list: async (subject, request) => {
+            ownType(request?.resource?.type);
+            return recordDoor().decideOwnedList(subject, request);
+        }
+    };
+    Object.freeze(access);
     const hostAddonAuditEventName = (name) => {
         const checked = addonAuditEventName(name);
         refuseUndeclared(slug, name, declared);
@@ -153,6 +179,8 @@ export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPers
         zonedParts,
         keyedSerial: () => new KeyedSerial(),
         reviews,
-        registerReviewHandler: (handlerId, handler) => reviewDoor().registerHandler(slug, handlerId, handler)
+        registerReviewHandler: (handlerId, handler) => reviewDoor().registerHandler(slug, handlerId, handler),
+        allowSignedOutWrite: (route) => declareAddonSignedOutWrite(slug, route),
+        access
     });
 }

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/availability.d.ts

@@ -100,6 +100,21 @@ export declare function zonedParts(now: Date, timeZone: string): {
     year: number;
     month: number;
 };
+/** Whether a schedule is switched on: `enabled: false` turns it off, as the site gate reads it. */
+export declare function scheduleIsEnabled(schedule: Schedule): boolean;
+/**
+ * The first thing in a schedule that is not in its exact allowed shape, or
+ * `null`. The shape is an allowlist, so a misspelled key reads as a problem,
+ * never as an open window: top-level keys `name`, `description`, `message`
+ * (text), `timeZone` (a known IANA zone), `enabled` (true or false), `rules`
+ * (a list) and `exceptions` (only empty); each rule an object with `type`
+ * (`allow`, `deny` or absent), `days` (a non-empty list of weekday names) and
+ * `startTime` and `endTime` (HH:MM, both or neither). A `deny` rule closes its
+ * whole day, so times on it are a problem rather than silently ignored.
+ * Names the path (`rules[1].dayz`), never a value. The site gate lets a
+ * malformed schedule stay open; a policy must not (#2261).
+ */
+export declare function scheduleProblem(schedule: Schedule, fallbackZone: string): string | null;
 /**
  * Whether a schedule is open at `now`.
  *

package/lib/src/utils/availability.js

@@ -78,6 +78,94 @@ function minutesOf(hhmm) {
         return null;
     return hours * 60 + mins;
 }
+const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+function knownZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a schedule is switched on: `enabled: false` turns it off, as the site gate reads it. */
+export function scheduleIsEnabled(schedule) {
+    return toBoolean(schedule.enabled, true);
+}
+// Exactly the keys the site gate reads (resolveAvailability, scheduleIsOpen), plus `name`/`description`, which only label.
+// `exceptions` is declared on Schedule but nothing reads it, so only the empty list the shipped schedules carry is accepted.
+const SCHEDULE_KEYS = ['name', 'description', 'timeZone', 'rules', 'exceptions', 'enabled', 'message'];
+const RULE_KEYS = ['type', 'days', 'startTime', 'endTime'];
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The first thing in a schedule that is not in its exact allowed shape, or
+ * `null`. The shape is an allowlist, so a misspelled key reads as a problem,
+ * never as an open window: top-level keys `name`, `description`, `message`
+ * (text), `timeZone` (a known IANA zone), `enabled` (true or false), `rules`
+ * (a list) and `exceptions` (only empty); each rule an object with `type`
+ * (`allow`, `deny` or absent), `days` (a non-empty list of weekday names) and
+ * `startTime` and `endTime` (HH:MM, both or neither). A `deny` rule closes its
+ * whole day, so times on it are a problem rather than silently ignored.
+ * Names the path (`rules[1].dayz`), never a value. The site gate lets a
+ * malformed schedule stay open; a policy must not (#2261).
+ */
+export function scheduleProblem(schedule, fallbackZone) {
+    const top = schedule;
+    if (!isPlainObject(top))
+        return 'the schedule is not an object';
+    for (const key of Object.keys(top)) {
+        if (!SCHEDULE_KEYS.includes(key))
+            return `${key} is not a schedule setting`;
+    }
+    for (const key of ['name', 'description', 'message']) {
+        if (top[key] !== undefined && typeof top[key] !== 'string')
+            return `${key} is not text`;
+    }
+    if (top.exceptions !== undefined && !(Array.isArray(top.exceptions) && top.exceptions.length === 0)) {
+        return 'exceptions is not read by anything and must be empty';
+    }
+    const zone = schedule.timeZone === undefined ? fallbackZone : schedule.timeZone;
+    if (typeof zone !== 'string' || !zone.trim() || !knownZone(zone)) {
+        return `${schedule.timeZone === undefined ? 'the site time zone (ngdpbase.time-zone)' : 'timeZone'} is not a known time zone`;
+    }
+    if (schedule.enabled !== undefined && typeof schedule.enabled !== 'boolean')
+        return 'enabled is not true or false';
+    if (schedule.rules === undefined)
+        return null;
+    if (!Array.isArray(schedule.rules))
+        return 'rules is not a list';
+    for (const [i, rule] of schedule.rules.entries()) {
+        const at = `rules[${i}]`;
+        if (!isPlainObject(rule))
+            return `${at} is not an object`;
+        for (const key of Object.keys(rule)) {
+            if (!RULE_KEYS.includes(key))
+                return `${at}.${key} is not a rule setting`;
+        }
+        // Only `allow`, `deny` or no type: scheduleIsOpen reads anything but 'deny' as allow, so a typo like "Deny" would fail open.
+        if (rule.type !== undefined && rule.type !== 'allow' && rule.type !== 'deny')
+            return `${at}.type is not allow or deny`;
+        if (rule.days !== undefined) {
+            if (!Array.isArray(rule.days) || rule.days.length === 0)
+                return `${at}.days is not a non-empty list`;
+            if (rule.days.some((d) => typeof d !== 'string' || !WEEKDAYS.includes(d.trim().toLowerCase())))
+                return `${at}.days is not a list of weekday names`;
+        }
+        const given = ['startTime', 'endTime'].filter((f) => rule[f] !== undefined);
+        if (rule.type === 'deny' && given.length > 0)
+            return `${at}.${given[0]} is ignored on a deny rule, which closes its whole day`;
+        // With neither time a rule covers its whole day; with one, or a bad one, it cannot be read.
+        if (given.length === 0)
+            continue;
+        for (const f of ['startTime', 'endTime']) {
+            if (minutesOf(rule[f]) === null)
+                return `${at}.${f} is not a time of day (HH:MM), or only one of startTime and endTime is given`;
+        }
+    }
+    return null;
+}
 /**
  * Whether a schedule is open at `now`.
  *

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;