@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

package/lib/src/utils/policyAttributes.js

@@ -1,39 +1,74 @@
-/**
- * The vocabulary of a policy `condition` (#2261): attribute types, the
- * operator 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.
- */
 /** The types an attribute can be declared with. */
 export const ATTRIBUTE_TYPES = ['string', 'integer', 'boolean', 'identity', 'list'];
 /**
- * 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 const DATATYPES = ['string', 'integer', 'boolean', 'double', 'date', 'time', 'dateTime', 'anyURI'];
+/**
+ * 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 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 const MAX_IN_ITEMS = 256;
 export const MAX_GROUP_CHILDREN = 256;
 export const MAX_CONDITION_NODES = 512;
-const SCALARS = ['string', 'integer', 'boolean', 'identity'];
-/** The operators that compare one attribute with a value. */
-export const LEAF_OPERATORS = {
-    equals: { left: SCALARS },
-    'not-equals': { left: SCALARS },
-    in: { left: ['string', 'integer', 'identity'] },
-    'greater-or-equal': { left: ['integer'] },
-    'less-or-equal': { left: ['integer'] }
+/**
+ * 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 const COMPARISON_FUNCTIONS = {
+    'string-equal': { type: 'string', kind: 'equal' },
+    'integer-equal': { type: 'integer', kind: 'equal' },
+    'boolean-equal': { type: 'boolean', kind: 'equal' },
+    'string-is-in': { type: 'string', kind: 'is-in' },
+    'integer-is-in': { type: 'integer', kind: 'is-in' },
+    'integer-greater-than': { type: 'integer', kind: 'greater-than' },
+    'integer-greater-than-or-equal': { type: 'integer', kind: 'greater-than-or-equal' },
+    'integer-less-than': { type: 'integer', kind: 'less-than' },
+    'integer-less-than-or-equal': { type: 'integer', kind: 'less-than-or-equal' }
 };
-/** The operators that combine conditions. `not` takes one condition, these take a list. */
-export const GROUP_OPERATORS = ['any-of', 'all-of'];
-export const NOT_OPERATOR = 'not';
-/** Every operator, in the order the validator lists them. */
-export const CONDITION_OPERATORS = [...Object.keys(LEAF_OPERATORS), ...GROUP_OPERATORS, NOT_OPERATOR];
+/** The functions that combine conditions: XACML's logical functions. `not` takes one condition, these take a list. */
+export const GROUP_FUNCTIONS = ['and', 'or'];
+export const NOT_FUNCTION = 'not';
+/** Every function, in the order the validator lists them. */
+export const CONDITION_FUNCTIONS = [...Object.keys(COMPARISON_FUNCTIONS), ...GROUP_FUNCTIONS, NOT_FUNCTION];
+/** The keys of an argument: an attribute or a literal, and its datatype. */
+export const OPERAND_KEYS = ['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 const LEGACY_CONDITION_KEYS = {
+    attribute: '{ "attributeid": …, "datatype": … } as an argument of a function',
+    equals: 'string-equal, integer-equal or boolean-equal',
+    'not-equals': 'not around string-equal, integer-equal or boolean-equal',
+    in: 'string-is-in or integer-is-in',
+    'greater-or-equal': 'integer-greater-than-or-equal',
+    'less-or-equal': 'integer-less-than-or-equal',
+    'any-of': 'or',
+    'all-of': 'and'
+};
+/** The one example the validator shows for the old shape. */
+export 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 function datatypeOf(attributeType) {
+    if (attributeType === 'identity')
+        return 'string';
+    if (attributeType === 'list')
+        return null;
+    return attributeType;
+}
 /** The type a literal value has, or `null` when it is not a usable literal. */
 export function literalType(value) {
     if (typeof value === 'string')
@@ -76,32 +111,46 @@ export function valueFits(attributeType, value) {
 }
 /**
  * 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 function compareLeaf(operator, left, right) {
+export function compareLeaf(kind, left, right) {
     if (!isComparable(left))
         return undefined;
-    switch (operator) {
-        case 'equals':
+    switch (kind) {
+        case 'equal':
             return isComparable(right) && typeof right === typeof left ? left === right : undefined;
-        case 'not-equals':
-            return isComparable(right) && typeof right === typeof left ? left !== right : undefined;
-        case 'in':
+        case 'is-in':
             if (right instanceof Set)
                 return right.has(left);
             return Array.isArray(right) && right.every((v) => isComparable(v) && typeof v === typeof left) ? right.includes(left) : undefined;
-        case 'greater-or-equal':
+        case 'greater-than':
+            return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left > right : undefined;
+        case 'greater-than-or-equal':
             return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left >= right : undefined;
-        case 'less-or-equal':
+        case 'less-than':
+            return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left < right : undefined;
+        case 'less-than-or-equal':
             return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left <= right : undefined;
         default:
             return undefined;
     }
 }
+/** The key that names how rules are combined (#2330). */
+export const RULE_COMBINING_ALGORITHM_KEY = 'ngdpbase.access.rule-combining-algorithm';
+/** The only algorithm the evaluator implements; XACML's name for it. */
+export const SUPPORTED_COMBINING_ALGORITHMS = ['deny-overrides'];
+/** What Admin → Configuration says about the algorithm. */
+export 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 function combiningAlgorithmProblem(value) {
+    if (typeof value === 'string' && SUPPORTED_COMBINING_ALGORITHMS.includes(value))
+        return null;
+    return `${RULE_COMBINING_ALGORITHM_KEY} is ${JSON.stringify(value) ?? 'not set'}; the only value accepted is ${SUPPORTED_COMBINING_ALGORITHMS.map((a) => `"${a}"`).join(', ')}`;
+}
 /** `value` as an assurance level, or `undefined` when it is not 1, 2 or 3. Never coerces. */
 export function toAal(value) {
     return value === 1 || value === 2 || value === 3 ? value : undefined;
@@ -178,17 +227,28 @@ export function declaredSubjectAttributes(raw) {
  * declaration `subjectDeclarationProblem` refuses. Used on save, on load and at boot.
  */
 export function subjectAttributesProblems(raw, sensitive) {
+    return subjectAttributesFindings(raw, sensitive).map((f) => f.log);
+}
+/** {@link subjectAttributesProblems}, each also in plain words for the needs-attention entry. */
+export function subjectAttributesFindings(raw, sensitive) {
     if (raw === null || raw === undefined)
         return [];
-    if (typeof raw !== 'object' || Array.isArray(raw))
-        return ['ngdpbase.access.subject-attributes must be an object of attribute name to { type, from }'];
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{
+                log: 'ngdpbase.access.subject-attributes must be an object of attribute name to { type, from }',
+                plain: 'The list of user details that rules can check is not in a form the site can read, so none of them work. Fix or clear that list in Admin → Configuration.'
+            }];
+    }
     return Object.entries(raw).flatMap(([name, decl]) => {
         const pinned = Object.hasOwn(PINNED_SUBJECT_ATTRIBUTES, name) ? PINNED_SUBJECT_ATTRIBUTES[name] : undefined;
         if (pinned) {
             const same = !!decl && typeof decl === 'object' && decl.type === pinned.type && decl.from === pinned.from;
-            return same ? [] : [`subject attribute '${name}' in ngdpbase.access.subject-attributes cannot be redefined: it is built in (type ${pinned.type}, from ${pinned.from}) and keeps that meaning; remove it`];
+            return same ? [] : [{
+                    log: `subject attribute '${name}' in ngdpbase.access.subject-attributes cannot be redefined: it is built in (type ${pinned.type}, from ${pinned.from}) and keeps that meaning; remove it`,
+                    plain: `The user detail '${name}' is built into the site and cannot be redefined, so your version is ignored. Remove it from the list of user details in Admin → Configuration.`
+                }];
         }
-        const problem = subjectDeclarationProblem(name, decl, sensitive);
+        const problem = subjectDeclarationFinding(name, decl, sensitive);
         return problem ? [problem] : [];
     });
 }
@@ -199,21 +259,146 @@ export function subjectAttributesProblems(raw, sensitive) {
  * like). Said so a condition naming it is refused rather than silently unknown.
  */
 export function subjectDeclarationProblem(name, decl, sensitive) {
+    return subjectDeclarationFinding(name, decl, sensitive)?.log ?? null;
+}
+/** {@link subjectDeclarationProblem}, also in plain words. */
+function subjectDeclarationFinding(name, decl, sensitive) {
     const where = `subject attribute '${name}' in ngdpbase.access.subject-attributes`;
+    const plain = `The user detail '${name}' is not set up correctly, so a rule that checks it will not work. Fix it, or remove it, in the list of user details in Admin → Configuration.`;
     if (!decl || typeof decl !== 'object')
-        return `${where} must be an object with a type and a from`;
+        return { log: `${where} must be an object with a type and a from`, plain };
     if (!ATTRIBUTE_TYPES.includes(decl.type))
-        return `${where} has type ${JSON.stringify(decl.type)}; use one of ${ATTRIBUTE_TYPES.join(', ')}`;
+        return { log: `${where} has type ${JSON.stringify(decl.type)}; use one of ${ATTRIBUTE_TYPES.join(', ')}`, plain };
     const from = decl.from;
     const source = typeof from === 'string' ? SUBJECT_SOURCES.find((s) => from === s || (s !== 'sign-in' && from.startsWith(s))) : undefined;
     if (!source)
-        return `${where} reads from ${JSON.stringify(from)}; start it with ${SUBJECT_SOURCES.join(', ')}`;
+        return { log: `${where} reads from ${JSON.stringify(from)}; start it with ${SUBJECT_SOURCES.join(', ')}`, plain };
     if (source !== 'sign-in') {
         const field = from.slice(source.length);
         if (!field)
-            return `${where} reads from '${source}' with no field; write ${source}<field>`;
-        if (sensitive.includes(field))
-            return `'${source}${field}' cannot be used in a condition`;
+            return { log: `${where} reads from '${source}' with no field; write ${source}<field>`, plain };
+        if (sensitive.includes(field)) {
+            return {
+                log: `'${source}${field}' cannot be used in a condition`,
+                plain: `The user detail '${name}' reads private account data, which a rule may not check. Remove it from the list of user details in Admin → Configuration.`
+            };
+        }
+    }
+    return 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 function readDeclaredAsWritten(config, key) {
+    if (!config)
+        return null;
+    try {
+        // No unresolved read means no way to avoid resolving `$NAME`, so read nothing.
+        return typeof config.getUnresolvedProperty === 'function' ? config.getUnresolvedProperty(key, null) : null;
+    }
+    catch {
+        return null;
     }
+}
+/** Where an environment attribute may be read from: `schedule:<name>` or `config:<key>` (#2261 slice 4). */
+export const ENVIRONMENT_SOURCES = ['schedule:', 'config:'];
+/** The environment attributes a site declares. Anything not an object is ignored. */
+export function declaredEnvironmentAttributes(raw) {
+    return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+}
+/**
+ * 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 function environmentDeclarationProblem(name, decl) {
+    return environmentDeclarationFinding(name, decl)?.log ?? null;
+}
+/** {@link environmentDeclarationProblem}, also in plain words. */
+function environmentDeclarationFinding(name, decl) {
+    const where = `environment attribute '${name}' in ngdpbase.access.environment-attributes`;
+    const plain = `The check '${name}' (for rules that depend on a schedule or a setting) is not set up correctly, so a rule that uses it will not work. Fix it, or remove it, in the list of checks in Admin → Configuration.`;
+    if (!decl || typeof decl !== 'object')
+        return { log: `${where} must be an object with a type and a from`, plain };
+    if (decl.type !== 'boolean')
+        return { log: `${where} has type ${JSON.stringify(decl.type)}; schedule: and config: attributes are boolean only, so use "boolean"`, plain };
+    const from = decl.from;
+    const source = typeof from === 'string' ? ENVIRONMENT_SOURCES.find((s) => from.startsWith(s)) : undefined;
+    if (!source)
+        return { log: `${where} reads from ${JSON.stringify(from)}; start it with ${ENVIRONMENT_SOURCES.join(' or ')}`, plain };
+    if (!from.slice(source.length))
+        return { log: `${where} reads from '${source}' with no ${source === 'schedule:' ? 'schedule name' : 'key'}; write ${source}<${source === 'schedule:' ? 'name' : 'key'}>`, plain };
     return 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 function environmentAttributesProblems(raw) {
+    return environmentAttributesFindings(raw).map((f) => f.log);
+}
+/** {@link environmentAttributesProblems}, each also in plain words for the needs-attention entry. */
+export function environmentAttributesFindings(raw) {
+    if (raw === null || raw === undefined)
+        return [];
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{
+                log: 'ngdpbase.access.environment-attributes must be an object of attribute name to { type, from }',
+                plain: 'The list of checks that depend on a schedule or a setting is not in a form the site can read, so none of them work. Fix or clear that list in Admin → Configuration.'
+            }];
+    }
+    return Object.entries(raw).flatMap(([name, decl]) => {
+        const problem = environmentDeclarationFinding(name, decl);
+        return problem ? [problem] : [];
+    });
+}
+/**
+ * What the old plural `conditions` array's entry types become in the single `condition` (#2334).
+ * Only a user-attribute entry with an equality operator (`==` or `===`) has an equivalent: a string comparison.
+ */
+const CONDITIONS_DECLARATION = '{ "department": { "type": "string", "from": "profile:department" } }';
+const CONDITIONS_EXAMPLE = '{ "string-equal": [ { "attributeid": "subject:department", "datatype": "string" }, { "value": "IT", "datatype": "string" } ] }';
+/** The policies that carry a non-empty old plural `conditions` array, named by id or by position (#2334). An empty array limits nothing either way, so it is not named. */
+function policiesWithOldConditions(policies) {
+    if (!Array.isArray(policies))
+        return [];
+    return [...policies.entries()]
+        .filter(([, p]) => {
+        const c = p?.conditions;
+        return Array.isArray(c) && c.length > 0;
+    })
+        .map(([i, p]) => `'${typeof p.id === 'string' ? p.id : `#${i + 1}`}'`);
+}
+/**
+ * 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 function unenforcedConditionsNotice(policies) {
+    const names = policiesWithOldConditions(policies);
+    if (names.length === 0)
+        return null;
+    const one = names.length === 1;
+    return `${one ? 'This rule has' : 'These rules have'} an old 'conditions' list that the site ignores, so it doesn't limit anyone: ${names.join(', ')}. Move ${one ? 'it' : 'each one'} into ${one ? 'the' : 'its'} rule's condition, or remove it.`;
+}
+/**
+ * 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 function unenforcedConditionsLine(policies) {
+    const names = policiesWithOldConditions(policies);
+    if (names.length === 0)
+        return null;
+    return `${names.join(', ')} ${names.length === 1 ? 'has' : 'have'} a conditions array, which is not enforced: nothing reads it, so it limits no access. `
+        + `Replace it with the single condition in the XACML form. A user-attribute entry with the == or === operator becomes ${CONDITIONS_EXAMPLE}, `
+        + `which needs the attribute declared with a source in ngdpbase.access.subject-attributes, for example ${CONDITIONS_DECLARATION} (see docs/access-policies.md#subject-attributes). `
+        + 'The other entry types (time-range, ip-range, context-attribute, session-attribute, environment, and user-attribute with any other operator) have no equivalent: a rule you need cannot be written yet, so do not rely on it (#2334)';
+}

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

@@ -26,7 +26,7 @@ export interface RoleGrants {
 }
 /** A grant to one subject, with the policies that give it (#2067). */
 export interface SubjectGrant extends RoleGrant {
-    /** The ids of the allow policies that give it, lowest priority first. */
+    /** The ids of the allow policies that give it, in id order. */
     by: string[];
 }
 export interface SubjectGrants {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.43.0",
+  "version": "5.44.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -45,20 +45,20 @@
     "dotenv": "^18.0.9",
     "express": "^5.3.0",
     "express-session": "^1.19.0",
-    "fast-xml-parser": "^5.11.2",
+    "fast-xml-parser": "^5.12.0",
     "fs-extra": "^11.4.1",
     "ipaddr.js": "^2.5.0",
-    "jose": "^6.2.14",
-    "linkedom": "^0.18.14",
+    "jose": "^6.2.15",
+    "linkedom": "^0.18.15",
     "markdown-it": "^14.3.3",
     "minisearch": "7.2.0",
-    "mmdb-lib": "^3.0.3",
+    "mmdb-lib": "^3.0.4",
     "multer": "^2.4.0",
-    "otpauth": "^9.5.2",
+    "otpauth": "^9.6.0",
     "qrcode": "^1.5.4",
     "rrule-temporal": "2.2.8",
     "tar": "^7.5.22",
-    "temporal-polyfill": "1.0.6",
+    "temporal-polyfill": "1.0.8",
     "winston": "^3.17.0"
   }
 }