@jwilleke/ngdpbase-types 5.42.0 → 5.43.0

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

@@ -0,0 +1,141 @@
+/**
+ * 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 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.
+ */
+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.
+ */
+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[];
+}
+/** 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 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 operator 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
+ * 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;
+/** 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[];
+/**
+ * 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;
+export {};

package/lib/src/utils/policyAttributes.js

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+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.
+ */
+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 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 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 operator 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
+ * 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) {
+    if (!isComparable(left))
+        return undefined;
+    switch (operator) {
+        case 'equals':
+            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':
+            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':
+            return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left >= right : undefined;
+        case 'less-or-equal':
+            return typeof left === 'number' && typeof right === 'number' && Number.isInteger(right) ? left <= right : undefined;
+        default:
+            return undefined;
+    }
+}
+/** `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) {
+    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 }'];
+    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`];
+        }
+        const problem = subjectDeclarationProblem(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) {
+    const where = `subject attribute '${name}' in ngdpbase.access.subject-attributes`;
+    if (!decl || typeof decl !== 'object')
+        return `${where} must be an object with a type and a from`;
+    if (!ATTRIBUTE_TYPES.includes(decl.type))
+        return `${where} has type ${JSON.stringify(decl.type)}; use one of ${ATTRIBUTE_TYPES.join(', ')}`;
+    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(', ')}`;
+    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 null;
+}

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/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.43.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",