@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/cache/RegionCache.d.ts

@@ -0,0 +1,171 @@
+import type ICacheAdapter from './ICacheAdapter.js';
+import type { CacheStats } from './ICacheAdapter.js';
+import CacheDependencies, { type VersionLookup } from './CacheDependencies.js';
+/**
+ * Cache set options
+ */
+export interface CacheSetOptions {
+    /** Time to live in seconds */
+    ttl?: number;
+}
+/**
+ * Region cache statistics
+ */
+export interface RegionStats {
+    /** Region name */
+    region: string;
+    /** Number of keys in this region */
+    keys: number;
+    /** Global cache statistics */
+    globalStats: CacheStats;
+}
+/**
+ * Factory function type for getOrSet
+ */
+export type CacheFactory<T> = () => Promise<T>;
+/** Options for getOrSetVersioned. */
+export interface VersionedSetOptions extends CacheSetOptions {
+    /** Told whether the value came from the cache (true) or was computed (false); for hit/miss metrics. */
+    onResult?: (hit: boolean) => void;
+}
+/** The two calls the read-through needs from a store. */
+export interface VersionedStore {
+    get<T = unknown>(key: string): Promise<T | undefined | null>;
+    set(key: string, value: unknown, options?: CacheSetOptions): Promise<unknown>;
+}
+/**
+ * Read-through with data versions (#1751), over any store with get and set.
+ * Returns the stored value while every topic it was built from still has the
+ * version it had then; otherwise computes it again with `factory`, stores it
+ * with the versions it read (unless the render marked itself volatile), and
+ * returns it. RegionCache.getOrSetVersioned is this over a region.
+ */
+export declare function readThroughVersioned<T>(store: VersionedStore, versionOf: VersionLookup, key: string, factory: (deps: CacheDependencies) => Promise<T>, options?: VersionedSetOptions): Promise<T>;
+/**
+ * RegionCache - Cache wrapper that provides namespaced access to a cache adapter
+ *
+ * This class wraps a cache adapter and automatically prefixes all keys with a region name,
+ * providing isolation between different cache users (managers, components, etc.)
+ */
+declare class RegionCache {
+    private readonly adapter;
+    private readonly region;
+    private readonly prefix;
+    private readonly versionOf;
+    /**
+     * @param versionOf How to read a data topic's current version (CacheManager.version).
+     *                  Without it every topic reads as version 0, so only a
+     *                  volatile render or the TTL ends an entry.
+     */
+    constructor(adapter: ICacheAdapter, region: string, versionOf?: VersionLookup);
+    /**
+     * Create a full key by prefixing with the region
+     *
+     * @param {string} key - The cache key
+     * @returns {string} The prefixed key
+     */
+    private _getFullKey;
+    /**
+     * Remove region prefix from a key
+     *
+     * @param {string} fullKey - The prefixed key
+     * @returns {string} The key without region prefix
+     */
+    private _stripPrefix;
+    /**
+     * Get a value from the cache
+     *
+     * @param {string} key - The cache key
+     * @returns {Promise<T|undefined>} The cached value or undefined if not found
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache
+     *
+     * @param {string} key - The cache key
+     * @param {unknown} value - The value to cache
+     * @param {CacheSetOptions} [options] - Cache options
+     * @returns {Promise<void>}
+     */
+    set(key: string, value: unknown, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Delete one or more keys from the cache
+     *
+     * @param {string|string[]} keys - Single key or array of keys to delete
+     * @returns {Promise<void>}
+     */
+    del(keys: string | string[]): Promise<void>;
+    /**
+     * Clear all cache entries for this region
+     *
+     * @param {string} [pattern] - Optional pattern to match keys within the region
+     * @returns {Promise<void>}
+     */
+    clear(pattern?: string): Promise<void>;
+    /**
+     * Get keys matching a pattern within this region
+     *
+     * @param {string} [pattern='*'] - Pattern to match
+     * @returns {Promise<string[]>} Array of matching keys (without region prefix)
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics for this region
+     *
+     * @returns {Promise<RegionStats>} Cache statistics for this region
+     */
+    stats(): Promise<RegionStats>;
+    /**
+     * Check if a key exists in this region
+     *
+     * @param {string} key - The cache key
+     * @returns {Promise<boolean>} True if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get or set a value (cache-aside pattern)
+     *
+     * @param {string} key - The cache key
+     * @param {CacheFactory<T>} factory - Function to generate the value if not cached
+     * @param {CacheSetOptions} [options] - Cache options
+     * @returns {Promise<T>} The cached or generated value
+     */
+    getOrSet<T>(key: string, factory: CacheFactory<T>, options?: CacheSetOptions): Promise<T>;
+    /**
+     * Read-through with data versions (#1751). Returns the stored value while
+     * every topic it was built from still has the version it had then;
+     * otherwise computes it again with `factory`, stores it with the versions it
+     * read (unless the render marked itself volatile), and returns it.
+     *
+     * The factory declares what it reads: `deps.dependsOn('LedgerManager')`.
+     */
+    getOrSetVersioned<T>(key: string, factory: (deps: CacheDependencies) => Promise<T>, options?: VersionedSetOptions): Promise<T>;
+    /**
+     * Get multiple keys at once
+     *
+     * @param {string[]} keys - Array of cache keys
+     * @returns {Promise<Record<string, T|undefined>>} Object with keys as properties and cached values
+     */
+    mget<T = unknown>(keys: string[]): Promise<Record<string, T | undefined>>;
+    /**
+     * Set multiple keys at once
+     *
+     * @param {Record<string, unknown>} keyValuePairs - Object with keys and values to set
+     * @param {CacheSetOptions} [options] - Cache options
+     * @returns {Promise<void>}
+     */
+    mset(keyValuePairs: Record<string, unknown>, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Get the region name
+     *
+     * @returns {string} The region name
+     */
+    getRegion(): string;
+    /**
+     * Get the underlying adapter
+     *
+     * @returns {ICacheAdapter} The cache adapter
+     */
+    getAdapter(): ICacheAdapter;
+}
+export default RegionCache;

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

@@ -0,0 +1,48 @@
+/**
+ * The context an acting call carries (#1179, security-posture P1).
+ *
+ * P1: any entry point that decides, records, or acts on someone's behalf
+ * takes a context — mandatory and positional. The two contexts that exist for
+ * that are the request's subject (`PermissionSubject`, which is what
+ * `WikiContext.userContext` and `req.userContext` are) and the job's
+ * (`JobContext`, for boot, schedule and queued work). This is the union a
+ * manager accepts, so a caller forwards whichever it was given and never
+ * rebuilds one from its fields.
+ *
+ * What travels: who, from where (request / boot / schedule), the delegation
+ * the call arrived under, and the address it came from. What does not: roles.
+ * Authority is resolved at the moment of each decision, never carried.
+ */
+import type { PermissionSubject } from '../managers/UserManager.js';
+import type { JobContext } from './JobContext.js';
+export type ActorContext = PermissionSubject | JobContext;
+/**
+ * The fields an audit record takes from a context.
+ *
+ * An emitter spreads it — `{ eventType, ...who, …, metadata: { ...who.metadata, … } }`
+ * — rather than copying `user` and `ipAddress` across one at a time, so a
+ * field added here (`actor`, #1762 slice 3) reaches every row without
+ * touching every emitter. `scripts/check-audit-attribution.ts` holds every
+ * emitter to that.
+ */
+export interface ActorAttribution {
+    /** The account acted on: under a proxy grant, the person represented. */
+    user: string;
+    /** Who actually did it, present only when that is not `user` — under a proxy grant (#1762). */
+    actor?: string;
+    ipAddress: string | undefined;
+    /** `origin` always; `reason` / `requestedAt` for a job; `delegated` when the request came through a token, share or proxy grant (with `proxyGrantId` for a proxy). */
+    metadata: Record<string, unknown>;
+}
+export declare function isJobContext(ctx: ActorContext): ctx is JobContext;
+/**
+ * Who acted, for the record — read from the context, never guessed.
+ *
+ * A job says its origin and reason; a request says `origin: request`, the
+ * address, and whether it acted under a delegation. A token's or share's id
+ * is not repeated here: that record already carries it, and a config-change
+ * record naming a token id would be a second place to redact. A proxy grant's
+ * id is (`proxyGrantId`): it is not a credential, and it is what joins the row
+ * to the grant that allowed it (#1762).
+ */
+export declare function actorOf(ctx: ActorContext): ActorAttribution;

package/lib/src/context/ActorContext.js

@@ -0,0 +1,33 @@
+import { attributedTo } from './bootActions.js';
+import { proxyAttribution } from '../utils/proxyClaim.js';
+export function isJobContext(ctx) {
+    return 'origin' in ctx && 'requestedAt' in ctx;
+}
+/**
+ * Who acted, for the record — read from the context, never guessed.
+ *
+ * A job says its origin and reason; a request says `origin: request`, the
+ * address, and whether it acted under a delegation. A token's or share's id
+ * is not repeated here: that record already carries it, and a config-change
+ * record naming a token id would be a second place to redact. A proxy grant's
+ * id is (`proxyGrantId`): it is not a credential, and it is what joins the row
+ * to the grant that allowed it (#1762).
+ */
+export function actorOf(ctx) {
+    if (isJobContext(ctx)) {
+        return attributedTo(ctx);
+    }
+    // #1762 slice 3: a proxy claim names the person who acted beside the one
+    // represented. Never mixed with a token or share — every door refuses that
+    // subject — so the token and share kinds keep their precedence here.
+    const { metadata: proxyMeta, ...proxy } = proxyAttribution(ctx.viaProxy);
+    return {
+        user: ctx.username,
+        ...proxy,
+        ipAddress: ctx.ipAddress,
+        metadata: {
+            origin: 'request',
+            ...(ctx.viaToken ? { delegated: 'token' } : ctx.viaShare ? { delegated: 'share' } : proxyMeta)
+        }
+    };
+}

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

@@ -0,0 +1,194 @@
+/**
+ * ApiContext — Lightweight request context for API route handlers.
+ *
+ * Parallel to WikiContext (used for page rendering), ApiContext provides a
+ * clean, typed, consistent object for addon and core API routes. It replaces
+ * scattered access to `req.userContext`, `req.session`, and engine managers.
+ *
+ * Usage:
+ *   import { ApiContext, ApiError, sendApiError } from '../../../dist/src/context/ApiContext.js';
+ *
+ *   router.post('/reservations', async (req, res) => {
+ *     try {
+ *       const ctx = ApiContext.from(req, engine);
+ *       await ctx.requirePermission('page-edit');
+ *       const username = ctx.actingUsername();
+ *       // ...
+ *     } catch (err) {
+ *       if (err instanceof ApiError) return sendApiError(res, err);
+ *       res.status(500).json({ error: String(err) });
+ *     }
+ *   });
+ */
+import type { Request, Response } from 'express';
+import '../types/express.js';
+import { BaseContext } from './BaseContext.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { AgentTokenGrant, PermissionSubject, ProxyClaim } from '../managers/UserManager.js';
+import type { ShareGrant } from '../types/Share.js';
+import type { ReauthMode } from '../managers/AuthManager.js';
+import { type Decision } from '../types/Policy.js';
+/**
+ * Thrown by ApiContext guard methods (requirePermission, actingUsername).
+ * Route handlers should catch this and forward `status` to `res.status()`.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    /**
+     * 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 }`).
+     */
+    readonly reauth?: string | undefined;
+    constructor(status: number, message: string, 
+    /**
+     * 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?: string | undefined);
+}
+/**
+ * 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 declare function sendApiError(res: Response, err: ApiError, mode?: ReauthMode): void;
+export declare class ApiContext extends BaseContext {
+    /** Reference to the wiki engine */
+    readonly engine: WikiEngine;
+    /** Whether the caller has an active authenticated session */
+    readonly isAuthenticated: boolean;
+    /** Caller's username, or null for anonymous */
+    readonly username: string | null;
+    /** Caller's display name, or null */
+    readonly displayName: string | null;
+    /** Caller's email address, or null */
+    readonly email: string | null;
+    /** Caller's assigned roles (always an array, never undefined) */
+    readonly roles: string[];
+    /**
+     * 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/`.
+     */
+    readonly viaToken?: AgentTokenGrant;
+    /** The share this request presented, when it did (#1222). Carried for the same reason as `viaToken`. */
+    readonly viaShare?: ShareGrant;
+    /** 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. */
+    readonly viaProxy?: ProxyClaim;
+    /**
+     * 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.
+     */
+    readonly subject: PermissionSubject | null;
+    /**
+     * 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(): string | 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(): boolean;
+    private constructor();
+    /** The request this context was built from; the step-up answer needs its return page (#1745). */
+    private readonly 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: Request, engine: WikiEngine): ApiContext;
+    /**
+     * 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(): string;
+    /**
+     * 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 }
+     */
+    /**
+     * 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
+     */
+    requirePermission(permission: string): Promise<void>;
+    /**
+     * 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);
+     */
+    enforceDeny(permission: string, decision: Decision): Promise<never>;
+}