@jwilleke/ngdpbase-types 5.42.0 → 5.44.0

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;

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

@@ -0,0 +1,74 @@
+import type { Policy } from '../types/Policy.js';
+/**
+ * Where the denies an administrator marked as checked are kept (#2355): rule id to the fingerprint of
+ * the rule as it was then. A mark hides the dashboard item and is read by nothing that decides access.
+ */
+export declare const CHECKED_DENIES_KEY = "ngdpbase.access.checked-denies";
+/** Where the "Mark as checked" button on the dashboard item posts (#2355). */
+export declare const DENY_CHECKED_ACTION = "/admin/access-policies/deny-checked";
+/** A stable hash of a whole rule, its id included, so a changed rule (or the same content under another name) is a different one (#2355). */
+export declare function policyFingerprint(policy: Policy): string;
+/** 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[];
+    /** Each `rewritten` line, in plain words, for the needs-attention entry (no permission ids, issue numbers or setting names). */
+    shown: Record<string, string>;
+}
+/** One finding for the start-up log (`log`, in full) and for the needs-attention entry (`plain`, in plain words). */
+export interface PolicyFinding {
+    log: string;
+    plain: string;
+    /** Set when the finding is an allow rule the upgrade notice already lists (`openWriteRules`); the needs-attention item leaves it out. */
+    coveredByUpgradeNotice?: boolean;
+    /** Set on a deny (#2355): the rule, its fingerprint now, and whether an administrator marked exactly this content as checked. */
+    deny?: {
+        id: string;
+        fingerprint: string;
+        checked: boolean;
+    };
+}
+/**
+ * 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; one an administrator marked as checked is still reported, with `deny.checked` set, #2355). Each is a log line in full and the same finding in plain words.
+ */
+export declare function pageWritePolicyFindings(policies: readonly Policy[], checked?: Readonly<Record<string, string>>): PolicyFinding[];
+/** The log lines of {@link pageWritePolicyFindings}. */
+export declare function pageWritePoliciesToReview(policies: readonly Policy[]): string[];
+/** An allow rule in force that lets more people write than the shipped rules do (#2355 handles denies, not this). */
+export interface OpenWriteRule {
+    id: string;
+    /** Who: everyone including signed-out visitors, every signed-in user, or the named roles other than admin. */
+    who: {
+        kind: 'anyone';
+    } | {
+        kind: 'authenticated';
+    } | {
+        kind: 'roles';
+        roles: string[];
+    };
+    /** The actions it grants; for `anyone` and `authenticated`, without page-read. `*` means everything. */
+    actions: string[];
+    resources: NonNullable<Policy['resources']>;
+}
+/**
+ * The allow rules in force that let `anyone` (signed-out visitors) or `authenticated` (every signed-in user)
+ * do more than page-read, or give page writes to a role other than admin. Deny rules are left out.
+ * Computed from the policies it is given, so what it returns follows the current policies.
+ */
+export declare function openWriteRules(policies: readonly Policy[]): OpenWriteRule[];

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;

package/lib/src/utils/permissionCatalog.js

@@ -50,6 +50,25 @@ export function withRetiredExpanded(names) {
     }
     return out;
 }
+/**
+ * The pushed-pages permission for each page write (#2255). A page in a
+ * pushed category (shipped by the system or an add-on: `system`,
+ * `documentation`, `addon` as shipped) is changed by holders of
+ * `pushed-pages-<verb>`; any other page by holders of `page-<verb>`. Which
+ * categories are which is the policies' to say — each grants one or the
+ * other on `system-category` resources — so a page write is asked as either
+ * name, and the policies on the page's category decide.
+ */
+const PUSHED_PAGE_WRITES = {
+    'page-edit': 'pushed-pages-edit',
+    'page-delete': 'pushed-pages-delete',
+    'page-rename': 'pushed-pages-rename'
+};
+/** The names a policy may grant `action` under (#2255): a page write and its pushed-pages twin, else the action alone. */
+export function pageWriteAlternatives(action) {
+    const pushed = PUSHED_PAGE_WRITES[action];
+    return pushed ? [action, pushed] : [action];
+}
 /**
  * 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;

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

@@ -0,0 +1,19 @@
+/**
+ * Plain wording for dashboard items that more than one manager raises (#2354).
+ *
+ * The dashboard's "needs attention" and "not working" items are read by home
+ * users. Each says what is wrong and one thing to do, with no issue numbers,
+ * setting names, environment variable names, file paths or "see the log". The
+ * developer detail goes to the log, beside the call that marks the item.
+ */
+/** Where a staged restore is looked at and cancelled: the Backup page. */
+export declare const STAGED_RESTORE_FIX: {
+    fixUrl: string;
+    fixLabel: string;
+};
+/** A staged restore that was set aside at start-up instead of put back (#1876, #1985). */
+export declare function stagedRestoreNotApplied(what: string): string;
+/** Said where the fix is a setting only the server can change: the app refuses to save it. */
+export declare const IN_SERVER_SETTINGS = "This is set in the server's settings, outside this page.";
+/** A configured folder on a drive that is not connected (`preflightConfiguredPath`). */
+export declare const UNUSABLE_FOLDER_REASON = "The drive or folder this feature keeps its files on is not connected, so it is switched off. Connect the drive again, or choose another folder, then restart the site.";

package/lib/src/utils/plainAttention.js

@@ -0,0 +1,18 @@
+/**
+ * Plain wording for dashboard items that more than one manager raises (#2354).
+ *
+ * The dashboard's "needs attention" and "not working" items are read by home
+ * users. Each says what is wrong and one thing to do, with no issue numbers,
+ * setting names, environment variable names, file paths or "see the log". The
+ * developer detail goes to the log, beside the call that marks the item.
+ */
+/** Where a staged restore is looked at and cancelled: the Backup page. */
+export const STAGED_RESTORE_FIX = { fixUrl: '/admin/backup', fixLabel: 'Open Admin → Backup' };
+/** A staged restore that was set aside at start-up instead of put back (#1876, #1985). */
+export function stagedRestoreNotApplied(what) {
+    return `A saved copy of ${what} was not put back when the site started, so what was there before is still in use. Open the Backup page to see what to do next.`;
+}
+/** Said where the fix is a setting only the server can change: the app refuses to save it. */
+export const IN_SERVER_SETTINGS = "This is set in the server's settings, outside this page.";
+/** A configured folder on a drive that is not connected (`preflightConfiguredPath`). */
+export const UNUSABLE_FOLDER_REASON = 'The drive or folder this feature keeps its files on is not connected, so it is switched off. Connect the drive again, or choose another folder, then restart the site.';

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

@@ -0,0 +1,232 @@
+/**
+ * The vocabulary of a policy `condition` (#2261, #2330): attribute types, the
+ * function table, the nesting limit, and how one comparison is decided.
+ * Pure: no I/O, no manager. The evaluator and the validator both import it,
+ * so the set of functions lives here and nowhere else.
+ *
+ * A condition follows XACML 3.0 in lowercase (#2330). A function is a key
+ * named for its XACML function, `string-equal`, whose value is the array of its
+ * arguments. An argument is an attribute, `{ "attributeid": "subject:id",
+ * "datatype": "string" }`, or a literal, `{ "value": "sales", "datatype":
+ * "string" }`. `datatype` is required on both.
+ */
+import type { PolicyFinding } from './pageWritePolicies.js';
+/** The types an attribute can be declared with. */
+export declare const ATTRIBUTE_TYPES: readonly ["string", "integer", "boolean", "identity", "list"];
+export type AttributeType = (typeof ATTRIBUTE_TYPES)[number];
+/**
+ * The datatypes a condition may name: the XACML 3.0 JSON profile's short
+ * names. Only `string`, `integer` and `boolean` have a function today, so a
+ * condition naming any other is refused as a datatype its function does not take.
+ */
+export declare const DATATYPES: readonly ["string", "integer", "boolean", "double", "date", "time", "dateTime", "anyURI"];
+/** The datatypes some function takes. */
+export type FunctionType = 'string' | 'integer' | 'boolean';
+/**
+ * How deep a condition may nest. Every function node counts, arguments that
+ * are attributes or values do not, so `or` > `and` > `not` > `string-equal` is 4
+ * and one more level is refused.
+ */
+export declare const MAX_CONDITION_DEPTH = 4;
+/**
+ * How wide a condition may be (#2261). Depth alone leaves the tree as wide as
+ * a config file can make it, and the evaluator walks it for every page a
+ * listing or search asks about. A literal `value` list in an `is-in`, the
+ * arguments of one `and` or `or`, and the function nodes of the whole condition
+ * are each capped.
+ */
+export declare const MAX_IN_ITEMS = 256;
+export declare const MAX_GROUP_CHILDREN = 256;
+export declare const MAX_CONDITION_NODES = 512;
+/** What a comparison does once both arguments are read. */
+export type ComparisonKind = 'equal' | 'is-in' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal';
+/** One function that compares two arguments: the datatype it takes and what it does. */
+export interface ConditionFunction {
+    type: FunctionType;
+    kind: ComparisonKind;
+}
+/**
+ * The functions that compare two arguments, by XACML 3.0 name (core spec,
+ * appendix A.3), in lowercase. `X-is-in` takes a value, then a bag: an attribute
+ * that is a list, or a literal whose `value` is an array.
+ */
+export declare const COMPARISON_FUNCTIONS: Readonly<Record<string, ConditionFunction>>;
+/** The functions that combine conditions: XACML's logical functions. `not` takes one condition, these take a list. */
+export declare const GROUP_FUNCTIONS: readonly ["and", "or"];
+export declare const NOT_FUNCTION = "not";
+/** Every function, in the order the validator lists them. */
+export declare const CONDITION_FUNCTIONS: readonly string[];
+/** The keys of an argument: an attribute or a literal, and its datatype. */
+export declare const OPERAND_KEYS: readonly ["attributeid", "value", "datatype"];
+/**
+ * The shape before #2330, key by key, and what replaces it, so the validator
+ * can say what to write. Not read by the evaluator: an old condition never holds.
+ */
+export declare const LEGACY_CONDITION_KEYS: Readonly<Record<string, string>>;
+/** The one example the validator shows for the old shape. */
+export declare const CONDITION_EXAMPLE = "{ \"string-equal\": [ { \"attributeid\": \"subject:department-id\", \"datatype\": \"string\" }, { \"value\": \"sales\", \"datatype\": \"string\" } ] }";
+/** The datatype an attribute of a declared type is referenced with: an identity is a string. A list has the datatype of its entries. */
+export declare function datatypeOf(attributeType: string): string | null;
+/** The type a literal value has, or `null` when it is not a usable literal. */
+export declare function literalType(value: unknown): 'string' | 'integer' | 'boolean' | null;
+/** Can a literal be compared with an attribute of this type? An identity is a string. */
+export declare function literalFits(attributeType: string, value: unknown): boolean;
+/**
+ * Does a value read for an attribute fit the type it is declared with? A
+ * value that does not is treated as missing by the reader, so a comparison on
+ * it is unknown and fails closed, not a definite false or true (#2261). Never
+ * coerces: "5" is not an integer. An empty string is a string, a value and not
+ * a missing one.
+ */
+export declare function valueFits(attributeType: string, value: unknown): boolean;
+/**
+ * Decides one comparison once both sides are read. `undefined` is unknown: a
+ * side that is missing, or not of a type the function can compare. Both sides
+ * must be the same kind of value (a string, a boolean or a whole number), so
+ * "5" never equals 5 and NaN never compares. `is-in` takes an array, or a Set the
+ * evaluator built from a literal list; every entry of an array must be the
+ * kind of value on the left. An empty string is a value, not a missing one.
+ */
+export declare function compareLeaf(kind: ComparisonKind, left: unknown, right: unknown): boolean | undefined;
+/** The key that names how rules are combined (#2330). */
+export declare const RULE_COMBINING_ALGORITHM_KEY = "ngdpbase.access.rule-combining-algorithm";
+/** The only algorithm the evaluator implements; XACML's name for it. */
+export declare const SUPPORTED_COMBINING_ALGORITHMS: readonly string[];
+/** What Admin → Configuration says about the algorithm. */
+export declare const DENY_OVERRIDES_EXPLANATION = "Any matching deny wins. Order and priority don't matter.";
+/** What is wrong with the value of `ngdpbase.access.rule-combining-algorithm`, or `null`. Used on save, on load and at boot. */
+export declare function combiningAlgorithmProblem(value: unknown): string | null;
+/** The assurance level a sign-in reached: NIST SP 800-63B, 1 to 3. */
+export type SubjectAal = 1 | 2 | 3;
+/** `value` as an assurance level, or `undefined` when it is not 1, 2 or 3. Never coerces. */
+export declare function toAal(value: unknown): SubjectAal | undefined;
+/**
+ * What a subject carries that bears on its assurance level (#2261 slice 3).
+ * Read from the request's subject, never from a request field: a caller
+ * cannot send an `aal` and have it believed.
+ */
+export interface AalFacts {
+    isAuthenticated?: boolean;
+    /** The session's sign-in record; absent on a session from before #1523. */
+    signIn?: {
+        aal?: unknown;
+    } | null;
+    /** The highest level the account's methods can reach; the level never exceeds it. */
+    aalCap?: number;
+    /** A token request: the level stored when the token was made. */
+    viaToken?: {
+        aal?: unknown;
+    } | null;
+    /** A share visitor has no sign-in. */
+    viaShare?: unknown;
+    /** A bearer JWT (Authentik): verified, but it records no sign-in level, so the subject has none (#2287). */
+    bearerWithoutLevel?: unknown;
+    /** A background job: the level stored when the job was requested. */
+    grantedAal?: unknown;
+    /** A background job (`JobSubject`): it has no session to read. */
+    resolveRolesNow?: unknown;
+}
+/**
+ * The subject's `subject:aal`, or `undefined` when it has none (#2261).
+ *
+ * - Not signed in, or a share visitor: none.
+ * - An agent token: the level stored with the token. A token made before this
+ *   stored one has none.
+ * - A background job: the level stored with the job's request. A job with
+ *   none (a schedule, boot, a request from before this) has none.
+ * - A bearer JWT that records no level (Authentik): none. It is not a session
+ *   from before sign-ins were recorded, so the AAL 1 rule below does not apply.
+ * - A session: its sign-in record's level; a session from before sign-ins
+ *   were recorded (#1523) is AAL 1, as `AuthManager` treats it.
+ *
+ * Capped at `aalCap`, as a role is. Reads the record; it never works the level
+ * out from factors.
+ */
+export declare function effectiveAal(subject: AalFacts | null | undefined): SubjectAal | undefined;
+/**
+ * The fields of a request's subject that bear on its level, copied by name so
+ * a subject rebuilt for a decision keeps them (the #1164 lesson: a field not
+ * forwarded is silently lost). Reads nothing else from it.
+ */
+export declare function aalFactsOf(subject: object | null | undefined): AalFacts;
+/** Where a subject attribute may be read from: `account:<field>`, `profile:<field>` or `sign-in`. */
+export declare const SUBJECT_SOURCES: readonly ["account:", "profile:", "sign-in"];
+/** One declared subject attribute, as `ngdpbase.access.subject-attributes` holds it. */
+export interface DeclaredSubjectAttribute {
+    type?: string;
+    from?: string;
+}
+/**
+ * `id` and `aal` mean what they mean here, whatever the configuration (or an
+ * add-on's default-config.json) says (#2287). `aal` is read from the sign-in
+ * record and `id` from the account; a site that could redefine either could
+ * make `subject:aal` read a field it controls and pass a "second factor" rule.
+ */
+export declare const PINNED_SUBJECT_ATTRIBUTES: Readonly<Record<string, DeclaredSubjectAttribute>>;
+/** The subject attributes a site declares, with `id` and `aal` pinned to their built-in meaning. Anything not an object is ignored. */
+export declare function declaredSubjectAttributes(raw: unknown): Record<string, DeclaredSubjectAttribute>;
+/**
+ * What is wrong with the value of `ngdpbase.access.subject-attributes` itself
+ * (#2287), one message each: not an object; `id` or `aal` declared with any
+ * meaning but the built-in one (the built-in is kept regardless; the same
+ * declaration as the built-in is harmless and not reported); and any other
+ * declaration `subjectDeclarationProblem` refuses. Used on save, on load and at boot.
+ */
+export declare function subjectAttributesProblems(raw: unknown, sensitive: readonly string[]): string[];
+/** {@link subjectAttributesProblems}, each also in plain words for the needs-attention entry. */
+export declare function subjectAttributesFindings(raw: unknown, sensitive: readonly string[]): PolicyFinding[];
+/**
+ * What is wrong with a subject attribute's declaration, or `null`: a `type`
+ * that is not known, a `from` that is not a subject source, or an account field
+ * that must never be read (`sensitive`, the password, email, roles and the
+ * like). Said so a condition naming it is refused rather than silently unknown.
+ */
+export declare function subjectDeclarationProblem(name: string, decl: DeclaredSubjectAttribute | undefined, sensitive: readonly string[]): string | null;
+/**
+ * A declaration map as written, every `$NAME` left unresolved, or `null` when
+ * it cannot be read. Declarations are read this way so a `$NAME` in one is
+ * judged and reported as written and an environment variable's value never
+ * reaches a message or a log line; a throwing read (an unset variable) is
+ * `null`, not an exception.
+ */
+export declare function readDeclaredAsWritten(config: {
+    getUnresolvedProperty?: (key: string, def?: unknown) => unknown;
+    getProperty: (key: string, def?: unknown) => unknown;
+} | null | undefined, key: string): unknown;
+/** Where an environment attribute may be read from: `schedule:<name>` or `config:<key>` (#2261 slice 4). */
+export declare const ENVIRONMENT_SOURCES: readonly ["schedule:", "config:"];
+/** One declared environment attribute, as `ngdpbase.access.environment-attributes` holds it. */
+export interface DeclaredEnvironmentAttribute {
+    type?: string;
+    from?: string;
+}
+/** The environment attributes a site declares. Anything not an object is ignored. */
+export declare function declaredEnvironmentAttributes(raw: unknown): Record<string, DeclaredEnvironmentAttribute>;
+/**
+ * What is wrong with an environment attribute's declaration, or `null`: a
+ * `type` that is not `boolean` (both sources yield a boolean and nothing
+ * else), a `from` that is not `schedule:<name>` or `config:<key>`, or one with
+ * no name or key after the prefix. Any configuration key may be read, secrets
+ * included (#2261): a condition can only compare the value, and the value is
+ * never written to a log, an audit record or a message.
+ */
+export declare function environmentDeclarationProblem(name: string, decl: DeclaredEnvironmentAttribute | undefined): string | null;
+/**
+ * What is wrong with the value of `ngdpbase.access.environment-attributes`
+ * itself, one message each: not an object, or a declaration
+ * {@link environmentDeclarationProblem} refuses. Used on save, on load and at boot.
+ */
+export declare function environmentAttributesProblems(raw: unknown): string[];
+/** {@link environmentAttributesProblems}, each also in plain words for the needs-attention entry. */
+export declare function environmentAttributesFindings(raw: unknown): PolicyFinding[];
+/**
+ * The words an administrator sees (the needs-attention entry and the save message) when a policy carries
+ * the old plural `conditions` array, or null when none does (#2334). Plain words: no issue number, no JSON.
+ */
+export declare function unenforcedConditionsNotice(policies: unknown): string | null;
+/**
+ * The start-up log line for the same policies, in full: the condition to write, the attribute
+ * declaration it needs, and the entry types with no equivalent (#2334). Null when none has one.
+ * Nothing in the decision path reads that array, so a rule written there limits no access.
+ */
+export declare function unenforcedConditionsLine(policies: unknown): string | null;