@jwilleke/ngdpbase-types 5.42.0 → 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

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

@@ -200,6 +200,21 @@ declare class ConfigurationManager extends BaseManager {
      * @throws {Error} If default configuration file cannot be loaded
      */
     private loadConfigurations;
+    /** What the #2255 page-write migration rewrote in memory, one sentence each; PolicyDecisionPoint reports it. */
+    pageWritePolicyMigration: string[];
+    /**
+     * #2255: before the merge, rewrite the custom layer's stored copies of the
+     * shipped role policies whose page writes moved to the category policies
+     * (`migrateStoredPageWritePolicies`). In memory only, like the other
+     * migrations here; one warning per policy changed.
+     */
+    private migrateStoredPageWritePolicies;
+    /**
+     * #2246: `ngdpbase.stores.<kind>.owner|encrypt` in the custom config have
+     * been ignored since #1505. One warning per key, and one needs-attention
+     * entry naming them all. Nothing is changed, carried over or removed.
+     */
+    private reportLegacyStoreKeys;
     /**
      * #642: One-shot migration shim. If the custom config sets either of the
      * legacy keys `ngdpbase.base-url` or `ngdpbase.baseURL`, copy the value