@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

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

@@ -1,39 +1,34 @@
+import type { Policy } from '../types/Policy.js';
 /**
- * The page-write policies after #2255, and the migration of a site's stored
- * copies of the old ones.
- *
- * Until #2255 the shipped role policies granted `page-edit`, `page-delete` and
- * `page-rename` on every page (`page: *`), and an `access: { edit: [admin] }`
- * stamp on each shipped page was the only thing keeping editors out of the
- * system and documentation pages. Those grants now sit on the
- * `system-category` resource type, one policy per group of categories, and the
- * stamp is gone.
- *
- * A site that ever saved `ngdpbase.access.policies` (the configuration editor,
- * the Shared folders screen) holds a full copy of the old role policies, and a
- * stored entry replaces the shipped one with the same id whole
- * (`src/utils/configFiles.ts`). Its `page-edit` on `page: *` would reopen every
- * pushed page to editors. So, before the merge, in memory:
- *
- * - a stored entry with a shipped id below loses the page writes it held on
- *   `page: *`; any it held that the shipped category policies do not give that
- *   role is kept, on the general category only, as a new policy
- *   `<id>-page-write`;
- * - every other policy that grants a page write on a `page` resource to a role
- *   other than admin, and every deny policy (a deny now overrides an allow
- *   whatever its priority), is reported and left as it is: it is the site's
- *   own choice.
- *
- * Pure: the caller logs and reports. The site's file is not rewritten; saving
- * the policy list from the configuration editor writes the migrated list.
+ * 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.
  */
-import type { Policy } from '../types/Policy.js';
+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
@@ -50,6 +45,30 @@ export declare function migrateStoredPageWritePolicies(policies: unknown): {
  * allow that grants a page write on a `page` resource to a role other than
  * admin (it reaches pushed pages), an allow that grants anything but
  * page-read to `anyone` or `authenticated` (#2261, #2283), and every deny (a deny now overrides any
- * allow, whatever the priorities).
+ * 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/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

@@ -1,38 +1,72 @@
 /**
- * The vocabulary of a policy `condition` (#2261): attribute types, the
- * operator table, the nesting limit, and how one comparison is decided.
+ * 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 operators lives here and nowhere else.
+ * 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];
 /**
- * How deep a condition may nest. Every node counts, leaves included, so
- * `any-of` > `all-of` > `not` > leaf is 4 and one more level is refused.
+ * 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 `in` list, the children of one
- * `any-of` or `all-of`, and the nodes of the whole condition are each capped.
+ * 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 against an attribute accepts, by operator. */
-interface LeafOperator {
-    /** Types the attribute on the left may have. */
-    left: readonly AttributeType[];
+/** 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 operators that compare one attribute with a value. */
-export declare const LEAF_OPERATORS: Readonly<Record<string, LeafOperator>>;
-/** The operators that combine conditions. `not` takes one condition, these take a list. */
-export declare const GROUP_OPERATORS: readonly ["any-of", "all-of"];
-export declare const NOT_OPERATOR = "not";
-/** Every operator, in the order the validator lists them. */
-export declare const CONDITION_OPERATORS: readonly string[];
+/**
+ * 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. */
@@ -47,13 +81,21 @@ export declare function literalFits(attributeType: string, value: unknown): bool
 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 operator can compare. Both sides
+ * 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. `in` takes an array, or a Set the
+ * "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(operator: string, left: unknown, right: unknown): boolean | undefined;
+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. */
@@ -131,6 +173,8 @@ export declare function declaredSubjectAttributes(raw: unknown): Record<string,
  * 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
@@ -138,4 +182,51 @@ export declare function subjectAttributesProblems(raw: unknown, sensitive: reado
  * 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;
-export {};
+/**
+ * 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;