@jwilleke/ngdpbase-types 5.41.1 → 5.43.0

package/lib/src/context/ApiContext.js

@@ -253,7 +253,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

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

@@ -175,6 +175,14 @@ export interface AddonProfileSection {
     title: string;
     /** Raw HTML rendered inside the card body; should contain form input fields. */
     html: string;
+    /**
+     * Font Awesome icon shown before the title in the card's header, such as
+     * `'fa-book'` (#1541). Optional; the host shows `fa-puzzle-piece` when it is
+     * missing or not a plain `fa-` name.
+     */
+    icon?: string;
+    /** Optional muted text shown after the title in the card's header (#1541). */
+    hint?: string;
 }
 /**
  * One entry per addon that contributed a profile section, returned by
@@ -596,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

@@ -56,6 +56,8 @@ interface BaseAttachmentProvider {
     filesInStoreForPage(location: StoreFileLocation, pageName: string): Promise<StoreFileEntry[]>;
     setFileMentionInStore(location: StoreFileLocation, id: string, pageName: string, mentioned: boolean): Promise<boolean>;
     deleteFileInStore(location: StoreFileLocation, id: string): Promise<StoreFileEntry | null>;
+    readStoreRenumbered(location: StoreFileLocation): Promise<Map<string, string>>;
+    noteStoreRenumbered(location: StoreFileLocation, pairs: ReadonlyMap<string, string>): Promise<void>;
     searchFilesInStore(location: StoreFileLocation, query: AssetQuery): Promise<AssetRecord[]>;
     privateRecordsInSharedIndex(): Array<{
         id: string;
@@ -117,6 +119,23 @@ export interface PutOptions {
      * record names the file by id only, so it is not recorded there.
      */
     importedFrom?: string;
+    /**
+     * A takeout import's file (#2188): the ids it had, the one to try first
+     * first, so a page still linking `/attachments/{id}` finds it again. The
+     * file is stored under the first that is free ({@link restoreIdIsFree});
+     * when none is, it gets a new id, as any upload does. Honoured only in a
+     * vault, never a shared folder or the shared pool; the import passes it
+     * only for one of its user's own stores. The stored id is in the returned
+     * metadata either way.
+     */
+    restoreIds?: readonly string[];
+    /**
+     * The ids files on the site held when the caller's run began, from
+     * {@link heldFileIds}, read once per run (#2188). With it, a restore checks
+     * the set instead of every store's folder on disk, and adds the id it
+     * stores to it.
+     */
+    heldIds?: Set<string>;
 }
 /**
  * The page-tied upload's options (#1396, #1398): today's callers name the page
@@ -216,6 +235,10 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
     /** What the last check for vault pages using shared-pool files found, and the degraded reason it set (#1842). */
     private poolFileFindings;
     private poolFileReason;
+    /** #2188: ids a restore has claimed and not yet written; one id is claimed by one put at a time. */
+    private readonly claimedRestoreIds;
+    /** #2188: ids a restore has stored since start, which a run's held ids read earlier may not list. */
+    private readonly restoredIds;
     private maxSize;
     private allowedTypes;
     /**
@@ -365,6 +388,42 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * store's file by id only, #2048), and FileManager, the owner, records it.
      */
     storeInPlace(ctx: ActorContext, place: FilePlace, file: PutFile, options?: PutOptions): Promise<StoredInPlace>;
+    /**
+     * Whether a file brought back by a takeout re-import may be stored under
+     * the id it had, `id` (#2188). Only an id of the shape a store gives
+     * (`isRestorableFileId`), and only when no file holds it: not the target
+     * store's index, not the shared pool, and no file on disk in any store of
+     * any owner or shared folder. A store names each file's bytes by its id
+     * (`{id}.ext`) in the clear, sealed or not, so another owner's sealed store
+     * is checked without its key. An id another file holds is never reused, so
+     * a takeout cannot claim another file's id, its own or anyone's.
+     *
+     * With `held` ({@link heldFileIds}, read once by the caller's run), the
+     * stores on disk are not read again: the id is free when the set lacks it,
+     * unless a restore stored that id since, which only the disk can settle.
+     */
+    private restoreIdIsFree;
+    /**
+     * The ids of every file on disk in any store of any owner or shared folder,
+     * by the names of their bytes (#2188). With `only`, stops at that id.
+     */
+    private storeIdsOnDisk;
+    /**
+     * The ids files in the site's stores hold now, read once, for a takeout
+     * import to pass as `PutOptions.heldIds` to each file it puts (#2188).
+     * Ids only, from the names of the bytes on disk; no store is opened.
+     */
+    heldFileIds(): Promise<Set<string>>;
+    /**
+     * The ids a takeout import gave the files of `ctx`'s own store `store` that
+     * could not keep their own, as takeout id → id here (#2188), or null when
+     * this context cannot open the store. Ids only.
+     */
+    ownStoreRenumbered(ctx: ActorContext, store: string): Promise<Map<string, string> | null>;
+    /** Adds `pairs` to {@link ownStoreRenumbered}'s, for a run that stored files under new ids (#2188). */
+    noteOwnStoreRenumbered(ctx: ActorContext, store: string, pairs: ReadonlyMap<string, string>): Promise<void>;
+    /** `ctx`'s own store `store`, as {@link ownStoreFingerprints} reaches it, or null. */
+    private ownStoreLocation;
     /**
      * The username an upload is recorded under (#1926): the person the context
      * names. Asked after policy has allowed the upload and before anything is