@jwilleke/ngdpbase-types 5.42.0 → 5.44.0

package/lib/src/context/ApiContext.d.ts

@@ -28,6 +28,7 @@ import type { AgentTokenGrant, PermissionSubject, ProxyClaim } from '../managers
 import type { ShareGrant } from '../types/Share.js';
 import { type ReauthMode } from '../managers/AuthManager.js';
 import { type Decision } from '../types/Policy.js';
+import type { OwnedAuditResource } from '../security/ownedRecords.js';
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
  * Route handlers should catch this and forward `status` to `res.status()`.
@@ -201,8 +202,14 @@ export declare class ApiContext extends BaseContext {
      * - an allow: a programming error. A refusal never silently passes.
      *
      * @example
-     * const d = await pdp.decide(ctx.getActor(), { action: 'ledger-adjust', resource: { type: 'ledger-entry', id } });
-     * if (!d.permit) await ctx.enforceDeny('ledger-adjust', d);
+     * const d = await pdp.decideOwnedRecord(ctx.subject, { action: 'phr-read', resource: { type: 'phr-record', id, attributes: { owner } } });
+     * if (!d.permit) await ctx.enforceDeny('phr-read', d, { type: 'phr-record', id, owner, ownerUser });
      */
-    enforceDeny(permission: string, decision: Decision): Promise<never>;
+    enforceDeny(permission: string, decision: Decision, resource?: OwnedAuditResource): Promise<never>;
+    /**
+     * The refusal of one add-on record (#1823), recorded before the error is
+     * thrown. `authorization-deny` is continue-on-failure, so a lost record does
+     * not change the refusal. `owner` is the stored identity @id.
+     */
+    private recordOwnedDenial;
 }

package/lib/src/context/ApiContext.js

@@ -6,6 +6,9 @@ import { BaseContext } from './BaseContext.js';
 import { answeredWithPage } from '../managers/AuthManager.js';
 import { STEP_UP_REASON } from '../types/Policy.js';
 import { CONSENT_PATH } from '../types/Consent.js';
+import { actorOf } from './ActorContext.js';
+import { AUDIT_EVENT } from '../utils/auditEventNames.js';
+import { recordAuditEvent } from '../utils/auditEvents.js';
 // ── ApiError ────────────────────────────────────────────────────────────────
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
@@ -253,7 +256,7 @@ export class ApiContext extends BaseContext {
         // one is asked as #1745 always has: holds the permission, may not act now —
         // exactly the condition under which the PDP writes STEP_UP_REASON.
         const stepUp = Boolean(this.request) && await this.holdsPermission(permission);
-        await this.enforceDeny(permission, { permit: false, applicable: true, reason: stepUp ? STEP_UP_REASON : 'policy_deny' });
+        await this.enforceDeny(permission, { permit: false, applicable: true, reason: stepUp ? STEP_UP_REASON : 'policy_deny', policyIds: [] });
     }
     /**
      * Turn a deny into the refusal (#1431) — the one implementation of refusal
@@ -269,13 +272,15 @@ export class ApiContext extends BaseContext {
      * - an allow: a programming error. A refusal never silently passes.
      *
      * @example
-     * const d = await pdp.decide(ctx.getActor(), { action: 'ledger-adjust', resource: { type: 'ledger-entry', id } });
-     * if (!d.permit) await ctx.enforceDeny('ledger-adjust', d);
+     * const d = await pdp.decideOwnedRecord(ctx.subject, { action: 'phr-read', resource: { type: 'phr-record', id, attributes: { owner } } });
+     * if (!d.permit) await ctx.enforceDeny('phr-read', d, { type: 'phr-record', id, owner, ownerUser });
      */
-    async enforceDeny(permission, decision) {
+    async enforceDeny(permission, decision, resource) {
         if (decision.permit) {
             throw new Error(`ApiContext.enforceDeny('${permission}') was handed an allow decision: it enforces only a deny`);
         }
+        if (resource)
+            await this.recordOwnedDenial(permission, decision, resource);
         if (decision.reason === STEP_UP_REASON && this.request) {
             // #1758: step-up is AuthManager's — the answer and its reauth-prompt record.
             const authManager = this.engine.getManager('AuthManager');
@@ -288,4 +293,32 @@ export class ApiContext extends BaseContext {
             ? new ApiError(403, 'Forbidden')
             : new ApiError(401, 'Authentication required');
     }
+    /**
+     * The refusal of one add-on record (#1823), recorded before the error is
+     * thrown. `authorization-deny` is continue-on-failure, so a lost record does
+     * not change the refusal. `owner` is the stored identity @id.
+     */
+    async recordOwnedDenial(permission, decision, resource) {
+        const who = this.subject
+            ? actorOf(this.subject)
+            : { user: 'anonymous', ipAddress: this.ipAddress, metadata: { origin: 'request' } };
+        const sink = this.engine.getManager?.('AuditManager');
+        await recordAuditEvent(sink, {
+            eventType: AUDIT_EVENT.AUTHORIZATION_DENY,
+            ...who,
+            action: permission,
+            resource: resource.id ?? '',
+            resourceType: resource.type,
+            result: 'deny',
+            reason: decision.reason || 'not permitted',
+            severity: 'medium',
+            metadata: {
+                ...who.metadata,
+                ...(resource.owner ? { owner: resource.owner } : {}),
+                ...(resource.ownerUser ? { ownerUser: resource.ownerUser } : {}),
+                ...(decision.policyIds?.length ? { policyIds: [...decision.policyIds] } : {}),
+                ...(decision.conditionNotMet?.length ? { conditionNotMet: [...decision.conditionNotMet] } : {})
+            }
+        });
+    }
 }

package/lib/src/context/BaseContext.d.ts

@@ -67,19 +67,13 @@ export declare abstract class BaseContext {
      * asked of the PDP (#1431 step 14): the token and share ceilings, then the
      * policies, with deny policies and role expansion.
      *
-     * For a check against a PAGE, ask `canAccess` on a context that has one —
-     * resource attributes beat global policy.
-     *
-     * #1504: with `attributes` — today `{ 'system-category': … }` — the same
-     * door asks about pages OF that kind, so a policy on the `system-category`
-     * resource type can decide (e.g. `page-public`: may this person make pages
-     * of this system-category public?). It is the policy question alone: unlike
-     * `canAccess` it walks none of one page's own tiers (private owner,
-     * frontmatter), so a page's owner gets no pass on it.
+     * For a check against a PAGE, ask {@link hasPermissionOn}: the PDP then
+     * reads the page's own attributes (its system-category, its owner) from the
+     * PIP (#2255). Asked here, a page write (`page-edit`, `-delete`, `-rename`)
+     * means "on some category", which is right for an affordance or a token's
+     * scope and wrong for a door.
      */
-    hasPermission(action: string, attributes?: {
-        'system-category'?: unknown;
-    }): Promise<boolean>;
+    hasPermission(action: string): Promise<boolean>;
     /**
      * Does this request's subject HOLD the permission (#1635)? Policy alone,
      * without the step-up freshness rule — for affordances only (show this
@@ -90,16 +84,22 @@ export declare abstract class BaseContext {
     /** One answer per question for this request — `hasPermission` and `hasPermissionOn` share it. */
     private cached;
     /**
-     * A capability asked about the page it is for (#1539). For a page in a
-     * vault: the container rule first — the owner, never a role, the same rule
-     * as Tier 0 of the page tiers — then the capability with the page's
-     * `vault`, asked about the page itself as the page tiers do — a `page: *`
-     * grant does not match a vault page's name, so only a policy on the `vault`
-     * resource type (`vault-owner`) decides there. For any other page, `hasPermission(action)`. A route that acts on
-     * a named page asks this instead of the bare capability, so a vault page is
-     * not judged by the caller's site-wide role.
+     * A capability asked about the page it is for (#1539, #2255). For a page in
+     * a vault: the container rule first — the owner, never a role, the same
+     * rule as Tier 0 of the page tiers — then the capability with the page's
+     * `vault`, so a policy on the `vault` resource type (`vault-owner`)
+     * decides. For any other page, the PDP is asked about the page by name and
+     * reads its system-category and owner from the PIP, so the policies on its
+     * category decide. A route that acts on a named page asks this instead of
+     * the bare capability.
      */
     hasPermissionOn(action: string, pageName: string): Promise<boolean>;
+    /**
+     * {@link hasPermissionOn} as an affordance (#2255): does the subject HOLD
+     * `action` on this page, policy alone, without the step-up rule? So the
+     * step-up fallback of a page-scoped check asks about the same page.
+     */
+    holdsPermissionOn(action: string, pageName: string): Promise<boolean>;
     /**
      * The identifiers that match audience-style filters — every role, plus the
      * username when there is one. Used where running the full evaluator per

package/lib/src/context/BaseContext.js

@@ -1,6 +1,6 @@
 'use strict';
 import { parsePrivatePageName } from '../utils/privateStorePath.js';
-import { permitsInVault } from '../utils/privateStoreAccess.js';
+import { holdsInVault, permitsInVault } from '../utils/privateStoreAccess.js';
 export class BaseContext {
     /**
      * The caller's subject as the middleware wrote it, or `null` for a context
@@ -57,25 +57,19 @@ export class BaseContext {
      * asked of the PDP (#1431 step 14): the token and share ceilings, then the
      * policies, with deny policies and role expansion.
      *
-     * For a check against a PAGE, ask `canAccess` on a context that has one —
-     * resource attributes beat global policy.
-     *
-     * #1504: with `attributes` — today `{ 'system-category': … }` — the same
-     * door asks about pages OF that kind, so a policy on the `system-category`
-     * resource type can decide (e.g. `page-public`: may this person make pages
-     * of this system-category public?). It is the policy question alone: unlike
-     * `canAccess` it walks none of one page's own tiers (private owner,
-     * frontmatter), so a page's owner gets no pass on it.
+     * For a check against a PAGE, ask {@link hasPermissionOn}: the PDP then
+     * reads the page's own attributes (its system-category, its owner) from the
+     * PIP (#2255). Asked here, a page write (`page-edit`, `-delete`, `-rename`)
+     * means "on some category", which is right for an affordance or a token's
+     * scope and wrong for a door.
      */
-    async hasPermission(action, attributes) {
+    async hasPermission(action) {
         const pdp = this.engineRef.getManager('PolicyDecisionPoint');
         if (!pdp)
             return false;
         // #637: hand over the already-resolved subject so the PDP need not
         // resolve the account and its roles again.
-        return this.cached(attributes ? `${action}\u0000${JSON.stringify(attributes)}` : action, () => (attributes
-            ? pdp.decide(this.getActor(), { action, resource: { type: 'page', id: '*' }, attributes }).then((d) => d.permit)
-            : pdp.permits(this.getActor(), action)));
+        return this.cached(action, () => pdp.permits(this.getActor(), action));
     }
     /**
      * Does this request's subject HOLD the permission (#1635)? Policy alone,
@@ -101,24 +95,47 @@ export class BaseContext {
         return promise;
     }
     /**
-     * A capability asked about the page it is for (#1539). For a page in a
-     * vault: the container rule first — the owner, never a role, the same rule
-     * as Tier 0 of the page tiers — then the capability with the page's
-     * `vault`, asked about the page itself as the page tiers do — a `page: *`
-     * grant does not match a vault page's name, so only a policy on the `vault`
-     * resource type (`vault-owner`) decides there. For any other page, `hasPermission(action)`. A route that acts on
-     * a named page asks this instead of the bare capability, so a vault page is
-     * not judged by the caller's site-wide role.
+     * A capability asked about the page it is for (#1539, #2255). For a page in
+     * a vault: the container rule first — the owner, never a role, the same
+     * rule as Tier 0 of the page tiers — then the capability with the page's
+     * `vault`, so a policy on the `vault` resource type (`vault-owner`)
+     * decides. For any other page, the PDP is asked about the page by name and
+     * reads its system-category and owner from the PIP, so the policies on its
+     * category decide. A route that acts on a named page asks this instead of
+     * the bare capability.
      */
     async hasPermissionOn(action, pageName) {
         const name = parsePrivatePageName(pageName);
-        if (!name)
-            return this.hasPermission(action);
+        if (!name) {
+            const pdp = this.engineRef.getManager('PolicyDecisionPoint');
+            if (!pdp)
+                return false;
+            // A stand-in decider with no `decide` (test doubles) answers the capability, as `holdsPermission` does.
+            if (typeof pdp.decide !== 'function')
+                return this.hasPermission(action);
+            return this.cached(`${action}\u0000${pageName}`, () => pdp.decide(this.getActor(), { action, resource: { type: 'page', id: pageName } }).then((d) => d.permit));
+        }
         if (!this.hasSubject())
             return false;
         const pdp = this.engineRef.getManager('PolicyDecisionPoint');
         return this.cached(`${action}\u0000${pageName}`, () => permitsInVault(pdp, this.getActor(), action, { owner: name.owner, vault: name.store, resource: pageName }));
     }
+    /**
+     * {@link hasPermissionOn} as an affordance (#2255): does the subject HOLD
+     * `action` on this page, policy alone, without the step-up rule? So the
+     * step-up fallback of a page-scoped check asks about the same page.
+     */
+    async holdsPermissionOn(action, pageName) {
+        const pdp = this.engineRef.getManager('PolicyDecisionPoint');
+        if (!pdp || typeof pdp.holds !== 'function')
+            return this.hasPermissionOn(action, pageName);
+        const name = parsePrivatePageName(pageName);
+        if (!name)
+            return this.cached(`holds\u0000${action}\u0000${pageName}`, () => pdp.holds(this.getActor(), action, { resource: { type: 'page', id: pageName } }));
+        if (!this.hasSubject())
+            return false;
+        return this.cached(`holds\u0000${action}\u0000${pageName}`, () => holdsInVault(pdp, this.getActor(), action, { owner: name.owner, vault: name.store, resource: pageName }));
+    }
     /**
      * The identifiers that match audience-style filters — every role, plus the
      * username when there is one. Used where running the full evaluator per

package/lib/src/context/JobContext.d.ts

@@ -67,6 +67,15 @@ export interface JobContext {
     viaProxy?: ProxyClaim;
     /** The address the requesting call came from (#1179), when there was one. Provenance for the record. */
     ipAddress?: string;
+    /**
+     * The assurance level (1 to 3) of the requester's session when the work was
+     * requested (#2261), which is the job's `subject:aal` whenever it runs. Taken
+     * from the requester's own session or token, never from an argument, so it
+     * cannot exceed it. Absent for work no session asked for (boot, a schedule,
+     * the command line) and for a job requested before it was stored: its
+     * `subject:aal` is missing and a condition on it fails closed.
+     */
+    aal?: 1 | 2 | 3;
     /** ISO 8601. When the work was requested, not when it ran. */
     requestedAt: string;
     /** Why, for origins with no person to ask. Free text, for the audit record. */
@@ -84,10 +93,23 @@ export interface JobContext {
 /** The shape a request-bound context exposes; both WikiContext and ApiContext satisfy it. */
 export interface RequestIdentity {
     username?: string | null;
+    /** With `signIn`, `aalCap` and `viaToken`, what the level the job stores is read from (#2261). */
+    isAuthenticated?: boolean;
+    signIn?: {
+        aal?: unknown;
+    } | null;
+    aalCap?: number;
     viaToken?: AgentTokenGrant;
     viaShare?: ShareGrant;
     viaProxy?: ProxyClaim;
     ipAddress?: string;
+    /** An `ApiContext` holds the request's subject here, a `WikiContext` as `userContext`: the level is read from that, not from the wrapper (#2287). */
+    subject?: object | null;
+    userContext?: object | null;
+    /** A `JobContext` handed back in: it already holds the level its requester's session had. */
+    origin?: unknown;
+    requestedAt?: unknown;
+    aal?: unknown;
 }
 /**
  * The username a request-origin job carries when the request had no identity.
@@ -150,6 +172,15 @@ export declare function jobContextFromOperator(username: string, reason: string,
  * a context to pass, including code that runs with no request at all.
  */
 export declare function jobContextFromSystem(systemPrincipal: string, reason: string, now?: Date): JobContext;
+/**
+ * Boot work done in one user's own vaults, on that user's behalf (#1815) —
+ * the start-up vault upgrades. The job carries the owner's username, so the
+ * vault container rule admits it as it admits any job carrying who asked, and
+ * what it may do there is the owner's own rights, resolved by policy when
+ * each write is decided. Never the system principal, which no vault admits.
+ * Like every job it carries no key, so an encrypted vault stays closed to it.
+ */
+export declare function jobContextForOwner(owner: string, reason: string, now?: Date): JobContext;
 /** As {@link jobContextFromSystem}, for work started by a timer rather than at boot. */
 export declare function jobContextFromSchedule(systemPrincipal: string, reason: string, now?: Date): JobContext;
 /**

package/lib/src/context/JobContext.js

@@ -30,6 +30,7 @@
  * enqueued by a token-bearing request escapes the agent-token ceiling simply by
  * becoming asynchronous.
  */
+import { effectiveAal, toAal } from '../utils/policyAttributes.js';
 /**
  * The username a request-origin job carries when the request had no identity.
  *
@@ -52,6 +53,7 @@ export function jobContextFromRequest(identity, now = new Date()) {
     return {
         username: identity?.username ?? ANONYMOUS_USERNAME,
         origin: 'request',
+        ...aalOf(identity),
         ...(identity?.viaToken ? { viaToken: identity.viaToken } : {}),
         ...(identity?.viaShare ? { viaShare: identity.viaShare } : {}),
         ...(identity?.viaProxy ? { viaProxy: proxyClaimForJob(identity.viaProxy) } : {}),
@@ -59,6 +61,24 @@ export function jobContextFromRequest(identity, now = new Date()) {
         requestedAt: now.toISOString()
     };
 }
+/**
+ * The level the requester's session or token has right now (#2261), as a field
+ * to store with the job; nothing when it has none. Read from the granting
+ * session's own subject whatever the caller passed (#2287): a request's subject
+ * as is, an `ApiContext`'s `subject`, a `WikiContext`'s `userContext`, or a
+ * `JobContext` handed back in, whose stored level is kept as it is.
+ */
+function aalOf(identity) {
+    if (!identity)
+        return {};
+    if (typeof identity.origin === 'string' && typeof identity.requestedAt === 'string') {
+        const kept = toAal(identity.aal);
+        return kept ? { aal: kept } : {};
+    }
+    const wrapped = identity.subject ?? identity.userContext;
+    const aal = effectiveAal(wrapped && typeof wrapped === 'object' ? (wrapped) : identity);
+    return aal ? { aal } : {};
+}
 /** The proxy claim without its key handle (#2047): the actor, grant and scopes stay for the ceiling and the record. */
 function proxyClaimForJob(claim) {
     const { keyHandle: _dropped, ...kept } = claim;
@@ -119,6 +139,17 @@ export function jobContextFromSystem(systemPrincipal, reason, now = new Date())
         reason
     };
 }
+/**
+ * Boot work done in one user's own vaults, on that user's behalf (#1815) —
+ * the start-up vault upgrades. The job carries the owner's username, so the
+ * vault container rule admits it as it admits any job carrying who asked, and
+ * what it may do there is the owner's own rights, resolved by policy when
+ * each write is decided. Never the system principal, which no vault admits.
+ * Like every job it carries no key, so an encrypted vault stays closed to it.
+ */
+export function jobContextForOwner(owner, reason, now = new Date()) {
+    return { username: owner, origin: 'boot', requestedAt: now.toISOString(), reason };
+}
 /** As {@link jobContextFromSystem}, for work started by a timer rather than at boot. */
 export function jobContextFromSchedule(systemPrincipal, reason, now = new Date()) {
     return { ...jobContextFromSystem(systemPrincipal, reason, now), origin: 'schedule' };
@@ -149,7 +180,9 @@ export function toPermissionSubject(ctx) {
         ...(ctx.viaShare ? { viaShare: ctx.viaShare } : {}),
         ...(ctx.viaProxy ? { viaProxy: ctx.viaProxy } : {}),
         // #1999: the job a scheduled run acts as, for the PIP to resolve.
-        ...(ctx.job ? { job: ctx.job } : {})
+        ...(ctx.job ? { job: ctx.job } : {}),
+        // #2261: the level stored when it was requested, for `subject:aal`.
+        ...(ctx.aal ? { grantedAal: ctx.aal } : {})
     };
 }
 /** One line for a log or an audit record: who, from where, and how. */

package/lib/src/ice/runExport.d.ts

@@ -31,11 +31,16 @@ export declare function exportSize(items: readonly IceItem[]): number;
 export declare function checkExportSize(items: readonly IceItem[], maxBytes: number): void;
 /**
  * Run the source's items through the chain, each shim's output the next
- * one's input, and return the one file the last shim made. What came before
+ * one's input, and return the file the last shim made. What came before
  * travels with each item while a shim keeps the count: earlier metadata
  * under later, as an import's chain does.
  *
+ * Items that are already `file`s skip the chain and join what it makes. One
+ * file is returned as it is; several, or any when `zipName` is given, are
+ * packed into `<zipName>.zip` (`export.zip` by default), each under its own
+ * name, a repeated name made unique. The zip is held to `maxBytes` too.
+ *
  * @throws IceExportFailed when a step holds more than `maxBytes`, a shim
- *   makes something other than what it declares, or the end is not one file
+ *   makes something other than what it declares, or the end is no file
  */
-export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings): Promise<IceItem>;
+export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings, zipName?: string): Promise<IceItem>;

package/lib/src/ice/searchExportSource.d.ts

@@ -0,0 +1,44 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import { type IceExportSource, type IceItem } from './types.js';
+/** Core's search export source. */
+export declare const SEARCH_EXPORT_SOURCE = "core.search";
+/** A search, as the page search takes it: the fields `/search` and `/api/assets/search` read. */
+export interface SearchExportParams {
+    q?: string;
+    types?: string;
+    mimeCategory?: string;
+    year?: number;
+    category?: string[];
+    keywords?: string[];
+    systemKeywords?: string[];
+    status?: string[];
+    searchIn?: string[];
+    since?: string;
+    until?: string;
+    date?: string;
+}
+/** The search's parameters from a query string or a body: known fields only, empty ones left out. */
+export declare function searchExportParams(src: Record<string, unknown> | null | undefined): SearchExportParams;
+/** What `read` and `mayExport` take as `ref`. */
+export declare const searchExportRef: (src: Record<string, unknown> | null | undefined) => string;
+/** A page as an NCM item: its text and what a document made from it shows. */
+export declare function pageItem(name: string, content: string, metadata: Record<string, unknown>): IceItem;
+interface Manager {
+    getManager<M>(name: string): M | null | undefined;
+}
+export interface SearchExportDeps {
+    engine: Manager;
+    /** May this user export this page alone (`page-export` for it, in its private store or shared folder)? */
+    mayExportPage(ctx: ActorContext, pageName: string): Promise<boolean>;
+    limits(): {
+        maxItems: number;
+        maxBytes: number;
+    };
+    /** Is the Export action for a search offered to this user (page-export held)? */
+    offered(ctx: ActorContext): Promise<boolean>;
+    /** Does this user hold `page-export` now? Throws the step-up answer when it needs a fresh sign-in. */
+    allowed(ctx: ActorContext): Promise<boolean>;
+    permits(ctx: ActorContext, permission: string): Promise<boolean>;
+}
+export declare function searchExportSource(deps: SearchExportDeps): IceExportSource;
+export {};

package/lib/src/ice/types.d.ts

@@ -641,6 +641,8 @@ export declare const EXPORT_FILE_KIND = "file";
 export interface ExportReadInfo {
     /** The shim that will make the file (`core.pdf`). */
     format: string;
+    /** Tell the user something about what was read (what was left out and why); shown with the finished export. */
+    note(text: string): void;
 }
 /**
  * The owner's door for reading the thing being exported (#2120, D5): a page
@@ -654,6 +656,8 @@ export interface IceExportSource {
     label?: string;
     /** The kind of the items it yields, e.g. `ncm` for a page. */
     yields: IceKind;
+    /** Make the export a zip with this name (`search-results`) even when it holds one file. */
+    zipAs?: string;
     /**
      * Would this context be allowed to export `ref`? Asked only to decide
      * whether to offer the Export action: an affordance, which records nothing.
@@ -724,6 +728,8 @@ export interface IceExportReport {
     startedAt?: string;
     finishedAt?: string;
     error?: string;
+    /** What the source says about what it read, such as how many items were left out. */
+    notes?: string[];
     file?: IceExportFile;
     /** When the file is let go (`ngdpbase.export.engine.keep-minutes`). */
     expiresAt?: string;

package/lib/src/managers/AddonsManager.d.ts

@@ -604,34 +604,6 @@ declare class AddonsManager extends BaseManager {
      * @param addonName  Name of the add-on (for logging)
      * @param addonPath  Filesystem path to the add-on directory
      */
-    /**
-     * Default edit-protection for a seeded addon page (#971, addons.md §3).
-     *
-     * §3 settled the mechanism: the seeder stamps frontmatter `access`, which
-     * Tier 1 of the evaluator honours directly, needs no `PolicyEvaluator`
-     * change, and is hash-neutral (`pageSourceHash` covers the body only, so
-     * adding metadata cannot disturb the #920 reseed comparison).
-     *
-     * §9 settled *who owns what*, and the two must be read together. A blanket
-     * admin lock would contradict the operator's decision that domain content
-     * pages "should be normal pages, purely seeded by the addon" — the addon
-     * provides a starting corpus and then lets go. So the default follows §9's
-     * ownership column rather than locking everything:
-     *
-     * | Category | Purpose | Default |
-     * |---|---|---|
-     * | `system` | Feature UI, site chrome — infrastructure | admin-only edit |
-     * | `documentation` | Help / docs — addon-owned | admin-only edit |
-     * | `general` | Domain content, demo — **instance-owned** | no stamp |
-     * | anything else | unclassified, treated as addon-owned | admin-only edit |
-     *
-     * An addon can always override by declaring its own `access`, which is the
-     * documented escape hatch in §3 and the reason the default is a default.
-     *
-     * @param category - The page's resolved `system-category`
-     * @returns The access object to stamp, or undefined to leave the page unprotected
-     */
-    private defaultAddonPageAccess;
     /**
      * Surface a page-level seed failure beyond the boot log (#951).
      *

package/lib/src/managers/AgentTokenManager.d.ts

@@ -82,6 +82,14 @@ export interface AgentTokenRecord {
     approvedBy?: string;
     /** The proxy grant it was minted under. Ending that grant ends this token; it works only while the grant is in force. */
     proxyGrantId?: string;
+    /**
+     * #2261: the assurance level (1 to 3) of the minting session when the token
+     * was made, which is `subject:aal` for every request the token makes. Taken
+     * from the session, never from the request, so it cannot exceed it. Absent
+     * on a token made before this was stored: its `subject:aal` is missing and a
+     * condition on it fails closed.
+     */
+    aal?: 1 | 2 | 3;
 }
 /** A record safe to return over the API — no hash. */
 export type AgentTokenPublic = Omit<AgentTokenRecord, 'hash'>;

package/lib/src/managers/AttachmentManager.d.ts

@@ -500,6 +500,17 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
         buffer: Buffer;
         metadata: AttachmentMetadata;
     } | null>;
+    /**
+     * May `ctx` read this file, by the rules `GET /attachments/:id` serves it
+     * under: a file in the requester's own store, else `asset-read`, and a
+     * private file only to its owner or their delegate (PIP). No bytes are read.
+     */
+    mayReadAttachment(attachmentId: string, ctx: ActorContext): Promise<boolean>;
+    /** A file's original bytes and metadata, when {@link mayReadAttachment} lets `ctx` read it; else null. */
+    readAttachmentFor(attachmentId: string, ctx: ActorContext): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
     /**
      * The requester's own private stores, as provider locations (#1460).
      *

package/lib/src/managers/AuditManager.d.ts

@@ -94,7 +94,6 @@ interface AccessContext {
 interface PolicyInfo {
     id: string;
     name: string;
-    priority?: number;
 }
 /**
  * Context for authentication events

package/lib/src/managers/AuthManager.d.ts

@@ -60,6 +60,15 @@ export interface FactorEntry {
      */
     preference?: number;
 }
+/** What an account can add or use toward a stronger sign-in (#2356); see `strongerSignInWays`. */
+export interface StrongerSignInWays {
+    addPasskey: boolean;
+    addTotp: boolean;
+    usePasskey: boolean;
+    useTotp: boolean;
+    password: boolean;
+    outside: string[];
+}
 export interface Factor {
     provider: string;
     primary: boolean;
@@ -797,6 +806,13 @@ declare class AuthManager extends BaseManager {
      * the request — so a passkey made here works only on that hostname.
      */
     private registerPasskeys;
+    /**
+     * #2317: the setting says passkeys are on, but the site's address cannot
+     * support them (base-url not set explicitly, or neither https nor localhost),
+     * so none are offered. The same rule registerPasskeys applies. Admin →
+     * Configuration says so on that setting's row and offers to turn it off.
+     */
+    passkeysCannotWork(): boolean;
     /** TOTP enrolment (#421), available whenever the credentials store is open. */
     private openTotp;
     /** Whether an authenticator app can be enrolled here (#421). */
@@ -826,6 +842,8 @@ declare class AuthManager extends BaseManager {
     private passkeyProvider;
     /** The host passkeys are tied to, or null when passkeys are off (#448). */
     passkeyRelyingParty(): PasskeyRelyingParty | null;
+    /** Can a passkey be added or used here at all (#2345)? False when passkeys are off or the address can't host them. */
+    passkeysAvailable(): boolean;
     /** Options for `username` to enrol a passkey (#448); the caller keeps `challenge` for verify. */
     /**
      * May this account sign in with `providerId`? Its `allowedAuthMethods`, when
@@ -1212,6 +1230,26 @@ declare class AuthManager extends BaseManager {
         now: Aal;
         ifEnrolled: Aal;
     }>;
+    /**
+     * The site's factors this account may use (`offered`: narrowed to its
+     * `allowedAuthMethods`), and of those the ones it can use now (`usable`: a
+     * factor that must be enrolled counts only once it is). One reading for
+     * the level the account can reach and for what it is told to add (#2356).
+     */
+    private accountFactors;
+    /**
+     * What this account can add or use here toward a stronger sign-in (#2356),
+     * for the sign-in banners and the confirm page's wording. Never a decision:
+     * who steps down and what step-up needs stay with `rolesAtSignIn` and
+     * `stepUpNeeded`. "Add" is a passkey or an authenticator app the site
+     * offers, the account is allowed and has not set up; "use" is one it has,
+     * is allowed, and the site offers (the app's code as step-up offers it).
+     * `password` is a password it has and is allowed, which the app's code
+     * needs to reach AAL2. `outside` names any other allowed sign-in method
+     * that reaches AAL2 by itself, such as an outside provider's.
+     * Computed per call; never cached across accounts.
+     */
+    strongerSignInWays(username: string): Promise<StrongerSignInWays>;
     /**
      * The roles an account holds at a lower level than they require only
      * because it has not enrolled a factor it is allowed (#1690): it acts with