@jwilleke/ngdpbase-types 5.42.0 → 5.44.0

package/lib/src/utils/policyAttributes.js

@@ -0,0 +1,404 @@
+/** The types an attribute can be declared with. */
+export const ATTRIBUTE_TYPES = ['string', 'integer', 'boolean', 'identity', 'list'];
+/**
+ * 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 `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;
+/**
+ * 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 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')
+        return 'string';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number' && Number.isInteger(value))
+        return 'integer';
+    return null;
+}
+/** Can a literal be compared with an attribute of this type? An identity is a string. */
+export function literalFits(attributeType, value) {
+    const type = literalType(value);
+    if (type === null)
+        return false;
+    return attributeType === 'identity' ? type === 'string' : attributeType === type;
+}
+/** A value a comparison can use: a string, a boolean, or a whole number (not NaN, ±Infinity or 2.5). */
+function isComparable(value) {
+    return typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isInteger(value));
+}
+/**
+ * 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 function valueFits(attributeType, value) {
+    switch (attributeType) {
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'list':
+            return Array.isArray(value) && value.every(isComparable);
+        default: // string, identity
+            return typeof value === 'string';
+    }
+}
+/**
+ * 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 function compareLeaf(kind, left, right) {
+    if (!isComparable(left))
+        return undefined;
+    switch (kind) {
+        case 'equal':
+            return isComparable(right) && typeof right === typeof left ? left === right : undefined;
+        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-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-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;
+}
+/**
+ * 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 function effectiveAal(subject) {
+    if (!subject?.isAuthenticated || subject.viaShare || subject.bearerWithoutLevel)
+        return undefined;
+    let raw;
+    if (subject.viaToken)
+        raw = toAal(subject.viaToken.aal);
+    else if (subject.resolveRolesNow)
+        raw = toAal(subject.grantedAal);
+    else
+        raw = toAal(subject.signIn?.aal) ?? (subject.signIn ? undefined : 1);
+    if (raw === undefined)
+        return undefined;
+    return toAal(Math.min(raw, typeof subject.aalCap === 'number' && subject.aalCap >= 1 ? subject.aalCap : 3));
+}
+/**
+ * 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 function aalFactsOf(subject) {
+    const s = (subject ?? {});
+    return {
+        signIn: s.signIn,
+        aalCap: typeof s.aalCap === 'number' ? s.aalCap : undefined,
+        viaToken: s.viaToken,
+        viaShare: s.viaShare,
+        bearerWithoutLevel: s.bearerWithoutLevel,
+        grantedAal: s.grantedAal,
+        resolveRolesNow: s.resolveRolesNow
+    };
+}
+/** Where a subject attribute may be read from: `account:<field>`, `profile:<field>` or `sign-in`. */
+export const SUBJECT_SOURCES = ['account:', 'profile:', 'sign-in'];
+/**
+ * `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 const PINNED_SUBJECT_ATTRIBUTES = {
+    id: { type: 'identity', from: 'account:id' },
+    aal: { type: 'integer', from: 'sign-in' }
+};
+/** The subject attributes a site declares, with `id` and `aal` pinned to their built-in meaning. Anything not an object is ignored. */
+export function declaredSubjectAttributes(raw) {
+    const declared = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    return { ...declared, ...PINNED_SUBJECT_ATTRIBUTES };
+}
+/**
+ * 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 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 [{
+                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 ? [] : [{
+                    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 = subjectDeclarationFinding(name, decl, sensitive);
+        return problem ? [problem] : [];
+    });
+}
+/**
+ * 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 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 { log: `${where} must be an object with a type and a from`, plain };
+    if (!ATTRIBUTE_TYPES.includes(decl.type))
+        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 { 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 { 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/privateStoreAccess.d.ts

@@ -3,8 +3,10 @@
  * every vault below it (docs/private-stores.md, Access).
  *
  * The owner, a share link the owner issued, or someone acting for the owner
- * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in,
- * admin included.
+ * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in
+ * through this rule. At a door, an administrator may also enter a vault that
+ * is not encrypted when `ngdpbase.vaults.admin-access` is true (#2255,
+ * {@link mayEnterVaultAtDoor}), and each such access is recorded.
  *
  * A share link gets in only for a vault it names (#1388), and only when the
  * caller names that vault: a question about the owner's container as a whole
@@ -25,8 +27,12 @@
  * slice 4).
  */
 import { type ActorContext } from '../context/ActorContext.js';
+/** The administrator's way into a vault (#2255): `PolicyDecisionPoint.adminMayEnterVault`. */
+interface AdminVaultEntry {
+    adminMayEnterVault?(ctx: unknown, owner: string, vault: string, resource: string, record?: boolean): Promise<boolean>;
+}
 /** The PDP surface a vault decision needs. */
-export interface VaultDecider {
+export interface VaultDecider extends AdminVaultEntry {
     decide(subject: unknown, request: {
         action: string;
         resource: {
@@ -36,10 +42,12 @@ export interface VaultDecider {
         attributes: Record<string, unknown>;
     }): Promise<{
         permit: boolean;
+        policyIds?: string[];
+        conditionNotMet?: string[];
     }>;
 }
 /** The PDP surface {@link holdsInVault} needs. */
-export interface VaultHolder {
+export interface VaultHolder extends AdminVaultEntry {
     holds(subject: unknown, action: string, on: {
         resource: {
             type: string;
@@ -48,6 +56,17 @@ export interface VaultHolder {
         attributes: Record<string, unknown>;
     }): Promise<boolean>;
 }
+/**
+ * The container rule at a door (#2255): the owner or their delegate
+ * ({@link mayActInPrivateContainer}), or else an administrator let in by
+ * `ngdpbase.vaults.admin-access` to a vault that is not encrypted, recorded
+ * when `record`. Lists never ask this; they keep the owner's rule alone.
+ */
+export declare function mayEnterVaultAtDoor(pdp: AdminVaultEntry | null | undefined, ctx: ActorContext, where: {
+    owner: string;
+    vault: string;
+    resource: string;
+}, record?: boolean): Promise<boolean>;
 export declare function mayActInPrivateContainer(ctx: ActorContext, owner: string, opts?: {
     vault?: string;
 }): boolean;
@@ -80,3 +99,4 @@ export declare function holdsInVault(pdp: VaultHolder | null | undefined, ctx: A
     vault: string;
     resource: string;
 }): Promise<boolean>;
+export {};

package/lib/src/utils/privateStoreAccess.js

@@ -3,8 +3,10 @@
  * every vault below it (docs/private-stores.md, Access).
  *
  * The owner, a share link the owner issued, or someone acting for the owner
- * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in,
- * admin included.
+ * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in
+ * through this rule. At a door, an administrator may also enter a vault that
+ * is not encrypted when `ngdpbase.vaults.admin-access` is true (#2255,
+ * {@link mayEnterVaultAtDoor}), and each such access is recorded.
  *
  * A share link gets in only for a vault it names (#1388), and only when the
  * caller names that vault: a question about the owner's container as a whole
@@ -29,6 +31,19 @@ import { shareNamesVault } from '../types/Share.js';
 import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
 import { isSharedFolderOwner } from './privateStorePath.js';
 import { permitsInSharedFolder } from './sharedFolderAccess.js';
+/**
+ * The container rule at a door (#2255): the owner or their delegate
+ * ({@link mayActInPrivateContainer}), or else an administrator let in by
+ * `ngdpbase.vaults.admin-access` to a vault that is not encrypted, recorded
+ * when `record`. Lists never ask this; they keep the owner's rule alone.
+ */
+export async function mayEnterVaultAtDoor(pdp, ctx, where, record = true) {
+    if (mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+        return true;
+    if (isSharedFolderOwner(where.owner) || typeof pdp?.adminMayEnterVault !== 'function')
+        return false;
+    return pdp.adminMayEnterVault(ctx, where.owner, where.vault, where.resource, record);
+}
 export function mayActInPrivateContainer(ctx, owner, opts = {}) {
     // #2125: the shared folders' container has no owner who acts; a folder is
     // decided by permission (`permitsInSharedFolder`), never by this rule.
@@ -67,7 +82,7 @@ export function mayActInPrivateContainer(ctx, owner, opts = {}) {
 export async function permitsInVault(pdp, ctx, action, where) {
     if (isSharedFolderOwner(where.owner))
         return permitsInSharedFolder(pdp, ctx, action, where.vault);
-    if (!pdp || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+    if (!pdp || !(await mayEnterVaultAtDoor(pdp, ctx, where)))
         return false;
     return (await pdp.decide(ctx, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
 }
@@ -78,7 +93,7 @@ export async function permitsInVault(pdp, ctx, action, where) {
  * folders are not asked: `permitsInVault` decides them by permission alone.
  */
 export async function holdsInVault(pdp, ctx, action, where) {
-    if (isSharedFolderOwner(where.owner) || typeof pdp?.holds !== 'function' || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+    if (isSharedFolderOwner(where.owner) || typeof pdp?.holds !== 'function' || !(await mayEnterVaultAtDoor(pdp, ctx, where, false)))
         return false;
     return pdp.holds(ctx, action, { resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } });
 }

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/lib/src/utils/username.d.ts

@@ -64,6 +64,17 @@ export declare const ACCOUNTLESS_PERSON_PREFIX = "person:";
  * anything else a username not yet converted.
  */
 export declare const IDENTITY_ID_PREFIX = "urn:";
+/**
+ * The prefix of an add-on's pages' author (#2255): `addon:<slug>`. The pages
+ * an add-on pushes to a site are authored by the add-on, as required pages
+ * are by `system`. No username may start with it, so no account is ever an
+ * add-on page's author, and a start-up conversion keeps it as it is.
+ */
+export declare const ADDON_AUTHOR_PREFIX = "addon:";
+/** The author of the pages add-on `slug` pushes (#2255). */
+export declare function addonAuthor(slug: string): string;
+/** True when `value` names an add-on as a page's author (#2255). */
+export declare function isAddonAuthor(value: unknown): boolean;
 /**
  * The prefix a start-up conversion gives a stored username that has no
  * account (#2041): `orphan:<name>`. The record is then nobody's: a later
@@ -86,7 +97,7 @@ export declare function isNoRecordedUser(value: unknown): boolean;
 /**
  * True when the name belongs to a principal rather than a user, is a "no user
  * recorded" value ({@link NO_RECORDED_USER}, #2097: an account by that name
- * would take over the records that hold it), or has the contact, `@id` or
- * orphan prefix.
+ * would take over the records that hold it), or has the contact, `@id`, orphan or
+ * add-on author (#2255) prefix.
  */
 export declare function isReservedUsername(username: unknown): boolean;

package/lib/src/utils/username.js

@@ -71,6 +71,21 @@ export const ACCOUNTLESS_PERSON_PREFIX = 'person:';
  * anything else a username not yet converted.
  */
 export const IDENTITY_ID_PREFIX = 'urn:';
+/**
+ * The prefix of an add-on's pages' author (#2255): `addon:<slug>`. The pages
+ * an add-on pushes to a site are authored by the add-on, as required pages
+ * are by `system`. No username may start with it, so no account is ever an
+ * add-on page's author, and a start-up conversion keeps it as it is.
+ */
+export const ADDON_AUTHOR_PREFIX = 'addon:';
+/** The author of the pages add-on `slug` pushes (#2255). */
+export function addonAuthor(slug) {
+    return `${ADDON_AUTHOR_PREFIX}${slug}`;
+}
+/** True when `value` names an add-on as a page's author (#2255). */
+export function isAddonAuthor(value) {
+    return typeof value === 'string' && value.length > ADDON_AUTHOR_PREFIX.length && value.startsWith(ADDON_AUTHOR_PREFIX);
+}
 /**
  * The prefix a start-up conversion gives a stored username that has no
  * account (#2041): `orphan:<name>`. The record is then nobody's: a later
@@ -96,10 +111,10 @@ export function isNoRecordedUser(value) {
 /**
  * True when the name belongs to a principal rather than a user, is a "no user
  * recorded" value ({@link NO_RECORDED_USER}, #2097: an account by that name
- * would take over the records that hold it), or has the contact, `@id` or
- * orphan prefix.
+ * would take over the records that hold it), or has the contact, `@id`, orphan or
+ * add-on author (#2255) prefix.
  */
 export function isReservedUsername(username) {
     const name = normalizeUsername(username);
-    return RESERVED_USERNAMES.includes(name) || NO_RECORDED_USER.includes(name) || name.startsWith(ACCOUNTLESS_PERSON_PREFIX) || name.startsWith(IDENTITY_ID_PREFIX) || name.startsWith(ORPHAN_PREFIX);
+    return RESERVED_USERNAMES.includes(name) || NO_RECORDED_USER.includes(name) || name.startsWith(ACCOUNTLESS_PERSON_PREFIX) || name.startsWith(IDENTITY_ID_PREFIX) || name.startsWith(ORPHAN_PREFIX) || name.startsWith(ADDON_AUTHOR_PREFIX);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.42.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"
   }
 }