@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

package/lib/src/security/signedOutWrites.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+/** The methods that only read. Every other method is held by the gate, so a new one (PROPFIND, MERGE, SEARCH…) fails closed. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** The methods an add-on may list. */
+const LISTABLE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/** Whether the method may change things, and so is held by the gate: anything but GET, HEAD and OPTIONS. */
+export function isWriteMethod(method) {
+    return !SAFE_METHODS.has(method.toUpperCase());
+}
+/**
+ * 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 const RESERVED_ADDON_SLUGS = new Set([
+    'addons', 'admin', 'agent', 'agents', 'assets', 'attachments', 'audit', 'auth', 'backup', 'catalog', 'check-updates',
+    'comments', 'config', 'consent', 'core', 'export', 'footnotes', 'import', 'install', 'keywords', 'login', 'logout',
+    'media', 'notifications', 'oidc', 'page', 'page-metadata', 'page-source', 'page-suggestions', 'pages', 'policies',
+    'policy', 'preview', 'profile', 'register', 'search', 'session', 'session-count', 'session-users', 'sessions', 'share',
+    'system', 'test', 'tokens', 'user', 'user-keywords', 'users', 'vault', 'wiki'
+]);
+/**
+ * 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 const CORE_SIGNED_OUT_WRITES = Object.freeze([
+    // Signing in. The caller has no session yet.
+    { method: 'POST', path: '/login', reason: 'password step of signing in' },
+    { method: 'POST', path: '/auth/magic-link', reason: 'asks for a sign-in link by email' },
+    { method: 'POST', path: '/auth/magic-link/verify', reason: 'completes a sign-in from the emailed link' },
+    { method: 'POST', path: '/auth/passkey/authenticate/verify', reason: 'signs in with a passkey' },
+    { method: 'POST', path: '/auth/oauth/:name', reason: 'starts a sign-in with an outside provider' },
+    { method: 'POST', path: '/auth/choose-account', reason: 'finishes an outside sign-in whose email is shared by several accounts' },
+    { method: 'POST', path: '/login/connect/cancel', reason: 'drops an outside identity waiting to be connected, from the login page' },
+    // The second factor. It needs the pending sign-in handle from the password step, not a session.
+    { method: 'POST', path: '/login/second-factor/email', reason: 'second factor: sends the approval email for the waiting sign-in' },
+    { method: 'POST', path: '/login/second-factor/complete', reason: 'second factor: completes the waiting sign-in' },
+    { method: 'POST', path: '/login/second-factor/cancel', reason: 'second factor: abandons the waiting sign-in' },
+    { method: 'POST', path: '/login/second-factor/totp', reason: 'second factor: authenticator-app code for the waiting sign-in' },
+    { method: 'POST', path: '/login/second-factor/device', reason: 'second factor: proof from a remembered browser for the waiting sign-in' },
+    { method: 'POST', path: '/login/approve', reason: 'approves or refuses a waiting sign-in from the emailed link, opened in any browser' },
+    // Signing out. A session that expired still has to be able to end.
+    { method: 'POST', path: '/logout', reason: 'ends the session; a signed-out caller is sent on to sign in' },
+    // Becoming a user, and getting back in.
+    { method: 'POST', path: '/register', reason: 'registration (the handler answers 404 when it is off)' },
+    { method: 'POST', path: '/recover-password', reason: 'password reset with the recovery words' },
+    { method: 'POST', path: '/invitation', reason: 'accepts an invitation by its token, which signs the person in' },
+    { method: 'POST', path: '/account/email/confirm', reason: 'confirms a changed email address from the emailed link, opened in any browser' },
+    // Public forms.
+    { method: 'POST', path: '/contact', reason: 'the public contact form (the handler answers 404 when it is off)' },
+    // First run: no account exists to sign in with. The handlers refuse once the site is installed.
+    { method: 'POST', path: '/install', reason: 'first-run installation, before any account exists' },
+    { method: 'POST', path: '/install/reset', reason: 'first-run installation, before any account exists' }
+]);
+/** What a route path means to Express: `:name` is one segment; the match ignores case and a trailing slash. */
+function matcherFor(path) {
+    const body = path
+        .split('/')
+        .map((segment) => (segment.startsWith(':') ? '[^/]+' : segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+        .join('/');
+    return new RegExp(`^${body}/?$`, 'i');
+}
+const entryOf = (route, owner) => ({ ...route, owner, matches: matcherFor(route.path) });
+const SEGMENT = /^(?:[A-Za-z0-9_~-][A-Za-z0-9._~-]*|:[A-Za-z][A-Za-z0-9_]*)$/;
+let addonEntries = [];
+let sealed = false;
+const coreEntries = CORE_SIGNED_OUT_WRITES.map((r) => entryOf(r, 'core'));
+/**
+ * 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 function declareAddonSignedOutWrite(slug, route) {
+    const refuse = (why) => {
+        throw new Error(`Add-on '${slug}' cannot allow a signed-out ${String(route?.method)} ${String(route?.path)}: ${why}`);
+    };
+    if (sealed)
+        refuse('the list is sealed once add-ons have loaded; declare it in register()');
+    if (RESERVED_ADDON_SLUGS.has(slug.toLowerCase()))
+        refuse(`'${slug}' is one of core's own route prefixes`);
+    if (!route || typeof route.method !== 'string' || !LISTABLE_METHODS.has(route.method.toUpperCase()))
+        refuse('the method must be POST, PUT, PATCH or DELETE');
+    if (typeof route.reason !== 'string' || route.reason.trim() === '')
+        refuse('say why in `reason`');
+    if (typeof route.path !== 'string')
+        return refuse('the path must be a string');
+    const own = [`/api/${slug}/`, `/addons/${slug}/`];
+    if (!own.some((prefix) => route.path.startsWith(prefix)))
+        refuse(`the path must be under ${own.join(' or ')}`);
+    const segments = route.path.split('/').slice(1);
+    if (segments.some((s) => !SEGMENT.test(s)))
+        refuse('the path may hold only literal segments and :name parameters');
+    addonEntries.push(entryOf({ ...route, method: route.method.toUpperCase() }, slug));
+}
+/** Close the list to add-ons. Called once, after they have loaded. */
+export function sealSignedOutWrites() {
+    sealed = true;
+}
+/** Test support: forget add-on declarations and reopen the list. Refuses outside `NODE_ENV=test`, so a sealed list stays sealed. */
+export function resetSignedOutWrites() {
+    if (process.env.NODE_ENV !== 'test' && !process.env.VITEST)
+        throw new Error('resetSignedOutWrites is for tests only (NODE_ENV=test)');
+    addonEntries = [];
+    sealed = false;
+}
+/** Every route on the list, core's then the add-ons'. */
+export function signedOutWriteRoutes() {
+    return [...coreEntries, ...addonEntries].map(({ method, path, reason, owner }) => ({ method, path, reason, owner }));
+}
+/** The reason the route is on the list, or null when a signed-out caller may not write to it. */
+export function signedOutWriteReason(method, path) {
+    const m = method.toUpperCase();
+    const hit = [...coreEntries, ...addonEntries].find((e) => e.method === m && e.matches.test(path));
+    return hit ? hit.reason : null;
+}

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

@@ -30,40 +30,38 @@ export interface PolicyResource {
     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`.
+ * 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 LeafCondition = {
-    attribute: string;
-} & ({
-    equals: unknown;
+export type ConditionOperand = {
+    attributeid: string;
+    datatype: string;
 } | {
-    'not-equals': unknown;
-} | {
-    in: unknown[] | string;
-} | {
-    'greater-or-equal': number | string;
-} | {
-    'less-or-equal': number | string;
-});
+    value: unknown;
+    datatype: string;
+};
 /**
- * A policy's condition: a {@link LeafCondition}, or `any-of` / `all-of` /
- * `not` over other conditions, nested at most 4 deep.
+ * 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;
  *
- * 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
+ * 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 = LeafCondition | {
-    'any-of': PolicyCondition[];
-} | {
-    'all-of': PolicyCondition[];
-} | {
-    not: PolicyCondition;
-};
+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. */
@@ -73,8 +71,6 @@ 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

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

@@ -0,0 +1,32 @@
+/**
+ * A save refused because another public page already has the title (#2371),
+ * or a name whose slug is the same as that page's (#2376).
+ *
+ * The message keeps the other page's id, for the log. What the reader sees is
+ * {@link pageTitleConflictText} and the link in {@link pageTitleConflictLink}:
+ * the title, never the id. A private-store clash is a plain Error that names
+ * nothing (#1461), so it is not this class.
+ */
+/** The page that has the name, as the error page and the editor's JSON carry it. */
+export interface ConflictingPage {
+    title: string;
+    url: string;
+    /** Only the slugs match: the view says the name is too close, not taken. */
+    tooClose?: boolean;
+}
+export declare class PageTitleConflictError extends Error {
+    readonly title: string;
+    readonly tooClose: boolean;
+    readonly code = "page-title-conflict";
+    /**
+     * @param title the title of the page that already has it
+     * @param pageId that page's id, for the message only
+     * @param requested the title the save asked for, when it differs only by case
+     * @param tooClose the titles differ and only their slugs match
+     */
+    constructor(title: string, pageId: string, requested?: string, tooClose?: boolean);
+}
+/** What the reader is told. */
+export declare function pageTitleConflictText(err: PageTitleConflictError): string;
+/** Where the title links to: the other page's title and its `/view/…` URL. */
+export declare function pageTitleConflictLink(err: PageTitleConflictError): ConflictingPage;