@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/context/ApiContext.js

@@ -0,0 +1,273 @@
+'use strict';
+// #1665: the Request augmentation (req.userContext, req.session). Imported here so the
+// emitted ApiContext.d.ts carries it to every add-on that typechecks against dist/.
+import '../types/express.js';
+import { BaseContext } from './BaseContext.js';
+import { STEP_UP_REASON } from '../types/Policy.js';
+// ── ApiError ────────────────────────────────────────────────────────────────
+/**
+ * Thrown by ApiContext guard methods (requirePermission, actingUsername).
+ * Route handlers should catch this and forward `status` to `res.status()`.
+ */
+export class ApiError extends Error {
+    status;
+    reauth;
+    constructor(status, message, 
+    /**
+     * For a step-up refusal (#1745): where the person re-authenticates,
+     * returning to the page they were on. Send it with the 403 so the page can
+     * offer the way forward, as core routes do (`{ error, reauth }`).
+     */
+    reauth) {
+        super(message);
+        this.status = status;
+        this.reauth = reauth;
+        this.name = 'ApiError';
+    }
+}
+/**
+ * Send a refusal — the one way it reaches the client, from core routes and
+ * every add-on route alike (#1749). JSON is `{ success: false, error, reauth? }`;
+ * text is the message, then where to sign in again for a step-up refusal.
+ * `page` is for a link the person followed in the browser: a step-up refusal
+ * redirects to the re-authenticate page, a 401 to sign-in (returning here),
+ * anything else is the message as text. A route never writes its own refusal:
+ * the step-up `reauth` is easy to drop.
+ */
+export function sendApiError(res, err, mode = 'json') {
+    // Only this site's re-authenticate page: an add-on's ApiError cannot send the person elsewhere.
+    const reauth = typeof err.reauth === 'string' && err.reauth.startsWith('/auth/reauth?') ? err.reauth : undefined;
+    if (mode === 'page') {
+        if (reauth) {
+            res.redirect(reauth);
+            return;
+        }
+        if (err.status === 401) {
+            res.redirect('/login?redirect=' + encodeURIComponent(res.req?.originalUrl || '/'));
+            return;
+        }
+        res.status(err.status).send(err.message);
+        return;
+    }
+    if (mode === 'text') {
+        res.status(err.status).send(reauth ? `${err.message}: ${reauth}` : err.message);
+        return;
+    }
+    res.status(err.status).json({ success: false, error: err.message, ...(reauth ? { reauth } : {}) });
+}
+/**
+ * The subject a request carries, refused when there is none (#1399).
+ *
+ * The session middleware writes one on every request — the signed-in user, or
+ * the anonymous PRINCIPAL it assigns when nobody has signed in — and the bearer
+ * and share paths overwrite it with their own. A request reaching here without
+ * one is a failure upstream, not an anonymous caller, and substituting anonymous
+ * would be the default actor security-posture P1 forbids.
+ */
+function subjectOf(req) {
+    const uc = req.userContext;
+    if (!uc || typeof uc.username !== 'string' || !uc.username) {
+        throw new Error('request has no subject: the session middleware writes one on every request (security-posture P1)');
+    }
+    return uc;
+}
+// ── ApiContext ───────────────────────────────────────────────────────────────
+export class ApiContext extends BaseContext {
+    /** Reference to the wiki engine */
+    engine;
+    /** Whether the caller has an active authenticated session */
+    isAuthenticated;
+    /** Caller's username, or null for anonymous */
+    username;
+    /** Caller's display name, or null */
+    displayName;
+    /** Caller's email address, or null */
+    email;
+    /** Caller's assigned roles (always an array, never undefined) */
+    roles;
+    /**
+     * The agent token this request arrived with, when it did (#1173).
+     *
+     * Absent before this: `from()` copied five fields off `req.userContext` and
+     * `viaToken` was not one of them, so every `ctx.hasPermission()` — including
+     * every addon API route using `requirePermission()` — resolved against the
+     * token OWNER's live roles with the token's scope ceiling unable to run. The
+     * same defect #1164 fixed in route code, reached through a context class
+     * instead, and invisible to a check that only scans `src/routes/`.
+     */
+    viaToken;
+    /** The share this request presented, when it did (#1222). Carried for the same reason as `viaToken`. */
+    viaShare;
+    /** The proxy grant this request acts under, when it does (#1762). Carried for the same reason as `viaToken`: a job started from this context keeps it. */
+    viaProxy;
+    /**
+     * The request's subject exactly as the middleware wrote it (#1179/#1382).
+     *
+     * The fields above are a flattened copy for convenience; this is the context
+     * itself, to forward to a manager door that takes one — never rebuilt from
+     * the fields, which is the #1173 defect. `null` for a request with no subject.
+     */
+    subject;
+    /**
+     * The address the request came from (#1179), read from the subject the
+     * middleware wrote — not a copy. Forwarded with the context, so a job or a
+     * record an add-on starts from it carries the provenance (#1667).
+     */
+    get ipAddress() {
+        const ip = this.subject?.ipAddress;
+        return typeof ip === 'string' && ip ? ip : undefined;
+    }
+    /**
+     * Whether the caller is signed in to a test account (#1805), read from the
+     * subject the middleware wrote (the account record's flag). An attribute for
+     * an add-on to enforce its own rules from; no policy reads it.
+     */
+    get isTest() {
+        return this.subject?.isTest === true;
+    }
+    constructor(engine, isAuthenticated, username, displayName, email, roles, viaToken, viaShare, viaProxy, subject = null, request = null) {
+        // #1399: the subject goes to BaseContext as given. The flattened fields
+        // below are a convenience copy for route code to READ; nothing may build a
+        // subject back out of them.
+        super(engine, subject);
+        this.engine = engine;
+        this.isAuthenticated = isAuthenticated;
+        this.username = username;
+        this.displayName = displayName;
+        this.email = email;
+        this.roles = roles;
+        this.viaToken = viaToken;
+        this.viaShare = viaShare;
+        this.viaProxy = viaProxy;
+        this.subject = subject;
+        this.request = request;
+    }
+    /** The request this context was built from; the step-up answer needs its return page (#1745). */
+    request;
+    /**
+     * Build an ApiContext from an Express request and engine reference.
+     *
+     * Reads `req.userContext` (set by the session middleware in app.ts) and
+     * normalises the values into a fully-typed object. Always succeeds — an
+     * unauthenticated request produces a context with `isAuthenticated: false`
+     * and an empty/anonymous roles array.
+     */
+    static from(req, engine) {
+        // #1212: a request with no middleware-written context is anonymous, field by field.
+        const uc = req.userContext ?? {};
+        const isAuthenticated = Boolean(uc['isAuthenticated'] ??
+            req.session?.isAuthenticated ??
+            false);
+        return new ApiContext(engine, isAuthenticated, (uc.username) ?? null, (uc.displayName) ?? null, (uc.email) ?? null, Array.isArray(uc.roles) ? (uc.roles) : [], uc.viaToken, uc.viaShare, uc.viaProxy, 
+        // #1399: forward the subject the middleware wrote, as it wrote it.
+        subjectOf(req), req);
+    }
+    // ── Guards ────────────────────────────────────────────────────────────────
+    /**
+     * The username this request acts as, for a feature that belongs to a
+     * person (a journal, a reservation). Asked AFTER `requirePermission`: policy
+     * decides whether the caller may, this only says whether there is someone
+     * to act as (#1430). A permission delegated to anonymous visitors still
+     * finds nobody here, so the refusal is a 401, never a crash on a missing
+     * name.
+     *
+     * @example
+     * await ctx.requirePermission('page-edit');
+     * const username = ctx.actingUsername(); // → 401 if nobody is signed in
+     */
+    actingUsername() {
+        // The anonymous subject carries a username ('anonymous'); it is not a
+        // person a journal or a reservation can belong to.
+        if (!this.isAuthenticated || !this.username) {
+            throw new ApiError(401, 'Authentication required');
+        }
+        return this.username;
+    }
+    // #1198: `hasRole` / `requireRole` are gone. A role name is not authority
+    // (security-posture.md P2): it skips the policy evaluator, deny policies and
+    // the agent-token scope ceiling. Ask `hasPermission` / `requirePermission`.
+    /**
+     * Returns true if the caller has the given permission.
+     *
+     * Asks the PDP (`PolicyDecisionPoint.permits`, #1431 step 14) — same canonical
+     * `PolicyEvaluator`-backed path that `WikiContext.hasPermission` uses.
+     * Honors anonymous/authenticated role expansion, deny policies, resource
+     * patterns, and the `'All'`/`'Authenticated'` role semantics. (#630)
+     *
+     * @example
+     * if (await ctx.hasPermission('user-read')) { // include PII fields }
+     */
+    /**
+     * #1399: the door is BaseContext's, which asks UserManager with the subject
+     * this context was handed. This method used to rebuild that subject from the
+     * flattened fields above — the #1173 defect, in the class where #1173
+     * happened. The rebuild listed username, roles, isAuthenticated, viaToken and
+     * viaShare, so it dropped `privateStoreHandle` and an addon API route could
+     * not see the caller's own sealed pages (#1382).
+     *
+     * @example
+     * if (await ctx.hasPermission('user-read')) { // include PII fields }
+     */
+    // hasPermission(action) is inherited from BaseContext.
+    /**
+     * Throws unless policy grants the caller this permission.
+     *
+     * #1399: the refusal classifies itself — 401 for a caller who has not
+     * signed in, 403 for one who has. That is the ONE sanctioned use of
+     * `isAuthenticated` (security-posture P2): it never decides, it only says
+     * which refusal to send after policy has already said no. Before this,
+     * every route paired `requireAuthenticated()` with this call to get the 401,
+     * which read as though authentication were half the gate.
+     *
+     * #1745: a refusal for someone who HOLDS the permission is the step-up one
+     * (#1635) — their sign-in is not fresh enough. It carries `reauth`, built
+     * where core routes build it (AuthManager.askForFreshSignIn, #1758), and the prompt is
+     * audited there; a delegated credential gets no `reauth`. The refusal itself
+     * is {@link enforceDeny}'s, shared with managers that ask the PDP directly.
+     *
+     * @example
+     * await ctx.requirePermission('search-user'); // → 401 anonymous, 403 signed in
+     */
+    async requirePermission(permission) {
+        if (await this.hasPermission(permission))
+            return;
+        // The boolean door carries no reason, so whether this "no" is the step-up
+        // 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' });
+    }
+    /**
+     * Turn a deny into the refusal (#1431) — the one implementation of refusal
+     * shaping, shared by {@link requirePermission} and every manager that asks
+     * the PDP itself. Always throws:
+     *
+     * - a step-up deny (`reason` {@link STEP_UP_REASON}) on a request:
+     *   `AuthManager.askForFreshSignIn` answers and records the reauth prompt —
+     *   `ApiError(403, …, reauth)`, or no `reauth` for a delegated credential
+     *   (agent token, share), which cannot give a fresh sign-in;
+     * - any other deny (policy, or a token, share or proxy ceiling): `ApiError(401)`
+     *   for a caller who has not signed in, `ApiError(403)` for one who has;
+     * - 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);
+     */
+    async enforceDeny(permission, decision) {
+        if (decision.permit) {
+            throw new Error(`ApiContext.enforceDeny('${permission}') was handed an allow decision: it enforces only a deny`);
+        }
+        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');
+            const answer = authManager
+                ? await authManager.askForFreshSignIn(this.request, this.request.userContext, permission, 'json')
+                : { permission, delegated: false, error: 'A fresh sign-in is needed' };
+            throw new ApiError(403, answer.error, answer.reauth);
+        }
+        throw this.isAuthenticated
+            ? new ApiError(403, 'Forbidden')
+            : new ApiError(401, 'Authentication required');
+    }
+}

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

@@ -0,0 +1,110 @@
+/**
+ * BaseContext — the permission door, implemented once (#1399).
+ *
+ * `WikiContext`, `ApiContext` and `ParseContext` each carry the caller's
+ * subject and each answered "may this subject do X?" in its own way. Three
+ * implementations of one question is how they drift: `ApiContext.hasPermission`
+ * REBUILT the subject from its own flattened fields, which is the #1173 defect
+ * in the class where #1173 happened. The rebuild listed `username`, `roles`,
+ * `isAuthenticated`, `viaToken` and `viaShare` — so it silently dropped
+ * `privateStoreHandle`, and an addon API route could not see the caller's
+ * sealed pages at all (#1382).
+ *
+ * This class holds the subject __exactly as given__ and asks `UserManager`
+ * with it. Nothing here copies a field out of a subject and builds a new one.
+ *
+ * __Not one merged context class.__ The three keep their own state and
+ * lifetimes — page and theme, API errors, parse state — and merging them would
+ * grow optional fields that are placeholders for most callers, which is the
+ * "parameter nothing reads" hazard security-posture P1 names. They share this
+ * door and nothing else.
+ *
+ * __No `hasRole` here.__ A role name is not authority (P2): it skips the
+ * policy evaluator, deny policies and the agent-token and share ceilings. A
+ * question about a NAMED user is `RoleManager.hasRole` / `userHoldsPermission`,
+ * which is a lookup, not a decision.
+ */
+import type { PermissionSubject } from '../managers/UserManager.js';
+/** The engine surface this door needs — `getManager`, nothing more. */
+export interface EngineLike {
+    getManager<T = unknown>(name: string): T | undefined | null;
+}
+export declare abstract class BaseContext {
+    /**
+     * The caller's subject as the middleware wrote it, or `null` for a context
+     * built without one (a boot-time render, a test fixture).
+     *
+     * Read it through {@link getActor}; that is the accessor callers and manager
+     * doors use, and it is the one place the anonymous case is decided.
+     */
+    protected readonly _subject: PermissionSubject | null;
+    protected readonly engineRef: EngineLike;
+    /**
+     * #636: per-instance memoisation of the permission door. The PROMISE is
+     * cached, not the result, so concurrent callers share one evaluation.
+     */
+    private readonly _permissionCache;
+    protected constructor(engine: EngineLike, subject: PermissionSubject | null);
+    /**
+     * The subject this context was handed, forwarded — never rebuilt.
+     *
+     * A caller with no session is `ANONYMOUS_SUBJECT`: a real, named caller that
+     * policy evaluates like any other, not an absence. That is why this returns
+     * a subject rather than `null` — "nobody in particular" is an answer, and
+     * making every call site invent its own fallback is how a default actor gets
+     * introduced (P1).
+     *
+     * The returned object is the stored reference. Do not copy it field by
+     * field: a rebuilt subject drops whatever the copier did not think of, which
+     * has so far been `viaToken` (#1173), `viaShare` (#1222) and
+     * `privateStoreHandle` (#1382).
+     */
+    getActor(): PermissionSubject;
+    /** True when a real subject was supplied — `getActor()` is not the anonymous fallback. */
+    hasSubject(): boolean;
+    /**
+     * May this caller perform `action` at all? The canonical global check,
+     * 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.
+     */
+    hasPermission(action: string, attributes?: {
+        'system-category'?: unknown;
+    }): Promise<boolean>;
+    /**
+     * Does this request's subject HOLD the permission (#1635)? Policy alone,
+     * without the step-up freshness rule — for affordances only (show this
+     * button, show this section), so a person whose sign-in is not fresh still
+     * sees the way to the prompt. A door or action asks {@link hasPermission}.
+     */
+    holdsPermission(action: string): Promise<boolean>;
+    /** 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.
+     */
+    hasPermissionOn(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
+     * result would be too expensive (search filtering).
+     */
+    getPrincipals(): string[];
+}
+export default BaseContext;

package/lib/src/context/BaseContext.js

@@ -0,0 +1,143 @@
+'use strict';
+import { parsePrivatePageName } from '../utils/privateStorePath.js';
+import { permitsInVault } from '../utils/privateStoreAccess.js';
+export class BaseContext {
+    /**
+     * The caller's subject as the middleware wrote it, or `null` for a context
+     * built without one (a boot-time render, a test fixture).
+     *
+     * Read it through {@link getActor}; that is the accessor callers and manager
+     * doors use, and it is the one place the anonymous case is decided.
+     */
+    _subject;
+    engineRef;
+    /**
+     * #636: per-instance memoisation of the permission door. The PROMISE is
+     * cached, not the result, so concurrent callers share one evaluation.
+     */
+    _permissionCache = new Map();
+    constructor(engine, subject) {
+        this.engineRef = engine;
+        this._subject = subject;
+    }
+    /**
+     * The subject this context was handed, forwarded — never rebuilt.
+     *
+     * A caller with no session is `ANONYMOUS_SUBJECT`: a real, named caller that
+     * policy evaluates like any other, not an absence. That is why this returns
+     * a subject rather than `null` — "nobody in particular" is an answer, and
+     * making every call site invent its own fallback is how a default actor gets
+     * introduced (P1).
+     *
+     * The returned object is the stored reference. Do not copy it field by
+     * field: a rebuilt subject drops whatever the copier did not think of, which
+     * has so far been `viaToken` (#1173), `viaShare` (#1222) and
+     * `privateStoreHandle` (#1382).
+     */
+    getActor() {
+        if (!this._subject) {
+            // #1399, operator 2026-09-20: a null user is a FAILURE, not a visitor.
+            // Anonymous is a principal the session middleware ASSIGNS — a real
+            // subject with its own role and its own grants. Substituting it here for
+            // a missing one would turn a bug upstream into a caller that looks
+            // legitimate, which is the default actor P1 forbids and the precise
+            // reason #1418 made `req.userContext` required rather than optional.
+            // A caller that genuinely acts as nobody passes ANONYMOUS_SUBJECT by
+            // name, or a JobContext that states its reason.
+            throw new Error('context has no subject: the caller must be forwarded, or ANONYMOUS_SUBJECT passed by name (security-posture P1)');
+        }
+        return this._subject;
+    }
+    /** True when a real subject was supplied — `getActor()` is not the anonymous fallback. */
+    hasSubject() {
+        return this._subject !== null;
+    }
+    /**
+     * May this caller perform `action` at all? The canonical global check,
+     * 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.
+     */
+    async hasPermission(action, attributes) {
+        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)));
+    }
+    /**
+     * Does this request's subject HOLD the permission (#1635)? Policy alone,
+     * without the step-up freshness rule — for affordances only (show this
+     * button, show this section), so a person whose sign-in is not fresh still
+     * sees the way to the prompt. A door or action asks {@link hasPermission}.
+     */
+    async holdsPermission(action) {
+        const pdp = this.engineRef.getManager('PolicyDecisionPoint');
+        if (!pdp)
+            return false;
+        // A stand-in decider with no `holds` (test doubles) answers with `permits`,
+        // which applies no step-up rule there either.
+        return this.cached(`holds\u0000${action}`, () => (typeof pdp.holds === 'function' ? pdp.holds(this.getActor(), action) : pdp.permits(this.getActor(), action)));
+    }
+    /** One answer per question for this request — `hasPermission` and `hasPermissionOn` share it. */
+    cached(key, decide) {
+        const hit = this._permissionCache.get(key);
+        if (hit)
+            return hit;
+        const promise = decide();
+        this._permissionCache.set(key, promise);
+        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.
+     */
+    async hasPermissionOn(action, pageName) {
+        const name = parsePrivatePageName(pageName);
+        if (!name)
+            return this.hasPermission(action);
+        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 }));
+    }
+    /**
+     * The identifiers that match audience-style filters — every role, plus the
+     * username when there is one. Used where running the full evaluator per
+     * result would be too expensive (search filtering).
+     */
+    getPrincipals() {
+        // Deliberately the RAW subject, not getActor(): with no subject the answer
+        // is an empty list, which matches nothing. Falling back to the anonymous
+        // subject here would hand back its role names and let a context with no
+        // caller match an audience — a filter must fail closed, and unlike the
+        // permission door there is no evaluator behind this to say no.
+        const subject = this._subject;
+        if (!subject)
+            return [];
+        const principals = Array.isArray(subject.roles) ? [...subject.roles] : [];
+        if (typeof subject.username === 'string' && subject.username.length > 0) {
+            principals.push(subject.username);
+        }
+        return principals;
+    }
+}
+export default BaseContext;