@jwilleke/ngdpbase-types 5.41.1 → 5.43.0

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

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import type { Policy } from '../types/Policy.js';
+/** 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[];
+}
+/**
+ * Rewrite the stored copies of the moved shipped policies, in `policies` (the
+ * custom layer's `ngdpbase.access.policies`), and return what was done and
+ * what an administrator should review. Returns the list to store in place of
+ * the input; the input is not changed.
+ */
+export declare function migrateStoredPageWritePolicies(policies: unknown): {
+    policies: unknown;
+    report: PageWritePolicyReport;
+};
+/**
+ * Policies in force that an administrator should review after #2255: an
+ * allow that grants a page write on a `page` resource to a role other than
+ * admin (it reaches pushed pages), an allow that grants anything but
+ * page-read to `anyone` or `authenticated` (#2261, #2283), and every deny (a deny now overrides any
+ * allow, whatever the priorities).
+ */
+export declare function pageWritePoliciesToReview(policies: readonly Policy[]): string[];

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

@@ -25,6 +25,8 @@ export declare function grantablePermissions<T>(definitions: Record<string, T> |
 export declare const RETIRED_PERMISSIONS: ReadonlyMap<string, readonly string[]>;
 /** The names with every retired permission replaced by what it stood for, de-duplicated, order kept. */
 export declare function withRetiredExpanded(names: readonly string[]): string[];
+/** The names a policy may grant `action` under (#2255): a page write and its pushed-pages twin, else the action alone. */
+export declare function pageWriteAlternatives(action: string): string[];
 /**
  * What the standard OpenID Connect sign-in scopes let an app see, in plain
  * words (#1572). They are not permissions, so they are not in the catalog;

package/lib/src/utils/permissionCatalog.js

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

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

@@ -0,0 +1,73 @@
+/**
+ * Record the security posture at boot and compare it against the previous boot
+ * (#1156, D19 of docs/security-posture.md).
+ *
+ * `config-change` (#1150) audits every change made through `setProperty()`,
+ * which leaves two holes:
+ *
+ * - An `app-custom-config.json` edited __directly on disk__ never passes
+ *   through `setProperty()` and emits nothing.
+ * - The state an instance __started in__ is never stated, only its deltas.
+ *
+ * Recording the posture at every start closes the second. Comparing that record
+ * against the previous start's closes the first: a change made on disk, or
+ * while the process was stopped, shows up as a difference between two
+ * consecutive boots __even though nothing observed the edit itself__.
+ *
+ * This is not the self-scoring D20 rejects. The comparison is against this
+ * instance's own previous state, a fact it holds, rather than against a
+ * recommended value set nobody can define.
+ */
+import type { PostureGroup } from './securityPosture.js';
+/** What a secret ingredient records instead of its value. */
+export declare const SECRET_PLACEHOLDER = "[secret]";
+/** The posture as recorded: one flat map of ingredient to value. */
+export type FlatPosture = Record<string, unknown>;
+/**
+ * Flatten the grouped posture for recording.
+ *
+ * A secret records that it is __set__ and never what it is set to. An entry
+ * naming a key alongside its value would reintroduce the disclosure
+ * `ngdpbase.config.sensitive-values` (its `secret` entries) exists to prevent, by a different route and
+ * into a file with longer retention than the logs it already guards.
+ */
+export declare function flattenPosture(groups: readonly PostureGroup[]): FlatPosture;
+export interface PostureDiff {
+    /**
+     * False when there is no previous record to compare against.
+     *
+     * Kept separate from "nothing changed", because they are different facts and
+     * only one of them is reassuring.
+     */
+    comparable: boolean;
+    changed: Array<{
+        key: string;
+        from: unknown;
+        to: unknown;
+    }>;
+    added: string[];
+    removed: string[];
+}
+/**
+ * Compare the posture now against the posture at the previous boot.
+ *
+ * __No previous record is `comparable: false`, never "no change".__ Only the
+ * last 1000 log lines are loaded for search (`FileAuditProvider.ts:610`), so on
+ * a busy instance the previous boot's record can fall outside the window.
+ * Reporting that as "nothing changed" would be a false all-clear at exactly the
+ * moment an operator is relying on the check.
+ *
+ * An ingredient added to or removed from the __view__ is reported separately
+ * from a __value__ change: removing an ingredient changes nothing about what
+ * the instance does (D4, D16), and folding both into "posture changed" would
+ * lose the distinction that matters when reading the log back.
+ */
+export declare function diffPostures(previous: FlatPosture | null, current: FlatPosture): PostureDiff;
+/**
+ * The line an operator reads at startup.
+ *
+ * A difference found here says explicitly that nothing observed the edit —
+ * otherwise the obvious question is why it is being reported at boot rather
+ * than as a `config-change`, and the answer is the whole point.
+ */
+export declare function describePostureDiff(diff: PostureDiff): string;

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

@@ -155,6 +155,12 @@ export interface PrivatePageName {
  * also its URL. No account can be called this (`RESERVED_USERNAMES`).
  */
 export declare const SHARED_FOLDER_OWNER = "shared-folders";
+/**
+ * Whether `id` has the shape a store gives a file (`crypto.randomUUID()`), so
+ * a takeout's file can be stored under it again (#2188). Anything else, a
+ * path or a pool's content hash among them, is never reused as a file name.
+ */
+export declare function isRestorableFileId(id: string): boolean;
 /** A shared folder page's name, and its URL without the leading slash: `shared/{folder}/{title}`. */
 export declare const SHARED_PAGE_NAME_PREFIX = "shared/";
 /** The first path segment of a shared folder's URL: `/shared/{folder}/{title}`. */