@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

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

@@ -0,0 +1,320 @@
+import BaseManager, { type BackupFolder } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type RecoveryWordsExport } from '../utils/recoveryWordsFile.js';
+/** The folder every signed-in user may open (decision; the shipped `shared-folder-default` policy). */
+export declare const DEFAULT_SHARED_FOLDER = "default";
+/** The Executive shared folder (#2095); who opens it is the shipped policies' (`shared-folder-executive-read`, `shared-folder-executive-file`, `shared-folder-admin`). */
+export declare const EXECUTIVE_SHARED_FOLDER = "executive";
+/** The folders every site has, made once the recovery words are confirmed (#2125, #2095). */
+export declare const SHIPPED_SHARED_FOLDERS: readonly string[];
+/** Who may read and who may file in a folder, as the Shared folders screen sets it (#2126). */
+export interface SharedFolderAccess {
+    /** Roles granted `shared-folder-read` on `shared/<name>` by the screen's policy. */
+    read: string[];
+    /** Roles granted `shared-folder-file` on `shared/<name>` by the screen's policy. */
+    file: string[];
+}
+/** A policy in force that reaches a folder and that the screen did not write: shipped, an add-on's, or the site's own. Shown, never changed here. */
+export interface SharedFolderOtherPolicy {
+    id: string;
+    name: string;
+    effect: string;
+    /** Its subjects as written (`role:editor`, `job:nightly`); empty: everyone, anonymous visitors included. */
+    subjects: string[];
+    /** Which of `shared-folder-read` and `shared-folder-file` it decides, as the PDP matches actions (an empty list or `*` is both). */
+    actions: string[];
+    /** It has an id the screen writes for this folder: saving the folder is refused until it is renamed or removed. */
+    reserved: boolean;
+}
+/** The words waiting for this admin, as the confirm step needs them: never the words. */
+export interface WaitingWords {
+    token: string;
+    /** Whether they replace a set already saved (a new set, #2144). */
+    replacing: boolean;
+}
+/** What Admin → Backup shows about the organization's recovery words: never the words. */
+export interface SharedFoldersWordsInfo {
+    /** Which set (`recoveryWordsId`): what the admin's confirmation is bound to. */
+    wordsId: string;
+    madeAt: string;
+    shownTo: string;
+    /** Whether any folder key is sealed for this set: such a set can never be discarded. */
+    protectsFolders: boolean;
+}
+/** The door said no: not allowed, or the request does not fit the state. Nothing was changed. */
+export declare class SharedFolderRefusedError extends Error {
+    readonly name = "SharedFolderRefusedError";
+}
+/** The words typed back are not the ones shown (#2144). Nothing was saved; the words still wait, to be typed again. */
+export declare class SharedFolderWordsMismatchError extends SharedFolderRefusedError {
+    constructor();
+}
+/** The keys cannot be used right now (no server key, or not the one they were made under); the message says why. */
+export declare class SharedFoldersUnavailableError extends Error {
+    readonly name = "SharedFoldersUnavailableError";
+}
+declare class SharedFolderManager extends BaseManager {
+    readonly description = "The organization's shared folders: each folder's key, the organization key and the recovery words (#1775, #2124)";
+    private storageDir;
+    /** The 32-byte wrap key derived from `NGDPBASE_SHARED_FOLDERS_KEY`, read once at start; null without one. */
+    private wrapKey;
+    private keyFingerprint;
+    /** Why the keys cannot be used, or null when they can. */
+    private unavailable;
+    private file;
+    private readonly pending;
+    private readonly serial;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    shutdown(): Promise<void>;
+    private configuredStorageDir;
+    /** The wrapped keys are in the backup; a backup from before #2124 has none, so it is optional. */
+    backupFolders(): BackupFolder[];
+    /** The organization's recovery words as made (never the words), or null: none made yet. */
+    recoveryWordsInfo(): SharedFoldersWordsInfo | null;
+    /**
+     * Whether the admin shown the current words confirmed saving them, at the
+     * wording's current version: their consent in `shared-folders-recovery-words`
+     * for this set exists (ConsentManager's fact, asked each time). False with
+     * no words, no ConsentManager, or no wording page (then nobody could have
+     * confirmed what it says).
+     */
+    recoveryWordsConfirmed(): Promise<boolean>;
+    /** Why the keys cannot be used now, or null when they can. */
+    unavailableReason(): string | null;
+    /**
+     * Make the organization's 12 recovery words, to show to the admin `ctx`
+     * once (decision 4). Nothing is saved: the words wait, in memory only, for
+     * that admin's `saveRecoveryWords` with the returned token, for
+     * `ngdpbase.shared-folders.words-pending-minutes`. A second call replaces
+     * the first set unsaved. Refused while a set is saved: an unconfirmed set is
+     * discarded first (`discardUnconfirmedWords`), and a saved set is replaced
+     * with `prepareNewRecoveryWords`.
+     */
+    prepareRecoveryWords(ctx: ActorContext): Promise<{
+        token: string;
+        words: string[];
+    }>;
+    /**
+     * Make a new set of recovery words to replace the saved set (#2144): the
+     * admin `ctx`, with a fresh sign-in (`admin-system` and the step-up
+     * permission). Shown and confirmed exactly as the first set; nothing changes
+     * until `saveRecoveryWords` with all 12 typed back, which seals every folder
+     * key for the new words and retires the old ones. Abandoned or discarded
+     * (`discardRecoveryWords`), the old set stays.
+     */
+    prepareNewRecoveryWords(ctx: ActorContext): Promise<{
+        token: string;
+        words: string[];
+    }>;
+    /** Make 12 words and hold them, for `ctx` only, until saved, discarded or expired. Replaces any set waiting for them. */
+    private holdNewWords;
+    /** The words waiting for `ctx` to type them back, or null: none, or they expired. Never the words. */
+    waitingWords(ctx: ActorContext): WaitingWords | null;
+    /**
+     * The words waiting for `ctx`, to download as a file or print (#2144),
+     * while they still wait: once saved they are gone and cannot be made again.
+     * Recorded first as `recovery-words-export` (who, which set, how; never the
+     * words; on-failure refuse). Refused for a token that is not the one shown
+     * to them, or expired; the words are not discarded by a refused export.
+     */
+    pendingRecoveryWords(ctx: ActorContext, token: string, how: RecoveryWordsExport): Promise<{
+        words: string[];
+        madeAt: Date;
+        wordsId: string;
+    }>;
+    /** Forget the words shown to `ctx` and not saved: they are never shown again. A set they were to replace stays. */
+    discardRecoveryWords(ctx: ActorContext): void;
+    /** The words waiting for `ctx`, or undefined; expired words are forgotten. */
+    private livePending;
+    /**
+     * Discard the saved recovery words while the admin shown them has not
+     * confirmed saving them (operator, 2026-10-29): any holder of
+     * `admin-system` may, so a reminder that nobody can clear (that admin's
+     * account deleted, say) can always be cleared by making a new set and
+     * confirming it themselves. Refused once the set is confirmed, and while
+     * any folder key is sealed for it (`createFolderKey` needs a confirmed set,
+     * so such a set was confirmed once). Recorded as
+     * `shared-folder-words-discard` before the words are removed (on-failure
+     * refuse).
+     */
+    discardUnconfirmedWords(ctx: ActorContext): Promise<void>;
+    /**
+     * Save the recovery words shown to `ctx` (`prepareRecoveryWords` or
+     * `prepareNewRecoveryWords`) once they proved they kept them: `typed` is
+     * all 12 typed back (#2144). The caller asks for the tick first, and records
+     * the confirmation with ConsentManager after (`wordsId`).
+     *
+     * - A token that is not the one shown to them, or expired: refused, and the
+     *   words are discarded.
+     * - Words that do not match: `SharedFolderWordsMismatchError`; nothing is
+     *   saved and the words still wait, to be typed again.
+     * - The first set: recorded as `shared-folder-words-create`, then saved.
+     *   Refused when a set was saved meanwhile.
+     * - A new set (#2144): asks the fresh sign-in again, seals every folder key
+     *   again for the new words from its server-key wrap, records
+     *   `shared-folder-words-replace`, then writes the new set and the sealed
+     *   keys as one file renamed into place: the old words stop opening the
+     *   folders, and on any failure before that the old set stays as it was.
+     *   Refused when the saved set changed meanwhile.
+     *
+     * Each record is on-failure refuse, written before the save.
+     *
+     * @returns Which set of words was saved (`recoveryWordsId`)
+     */
+    saveRecoveryWords(ctx: ActorContext, token: string, typed: string): Promise<string>;
+    /**
+     * Every folder key in `folders`, its recovery copy sealed again for the
+     * words of `recovery` (#2144), opened with the server key. Nothing is
+     * written; a key that cannot be opened throws, and the caller keeps the
+     * old set.
+     */
+    private sealedForWords;
+    /**
+     * Make folder `folderId`'s own key (decision 2): a random key, wrapped
+     * under the server key and sealed for the recovery words, so it needs the
+     * words to exist and to be confirmed saved by the admin shown them
+     * (`recoveryWordsConfirmed`; operator, 2026-10-29): no folder key is ever
+     * protected only by words nobody saved. Recorded as `shared-folder-key-create` before it is
+     * saved (on-failure refuse). The key itself is not returned; open it with
+     * `openFolderKey`.
+     */
+    createFolderKey(ctx: ActorContext, folderId: string): Promise<void>;
+    /**
+     * Folder `folderId`'s key, unwrapped with the server key, for a caller the
+     * PDP permits `shared-folder-read` on the folder (#2125). The caller holds
+     * it for the moment it needs it and zeroes it. The page and file doors do
+     * not call this: they reach the key through the store I/O
+     * (`sharedFolderKeyFor`), only for a context permitted on the folder.
+     */
+    openFolderKey(ctx: ActorContext, folderId: string): Promise<Buffer>;
+    /** Folder `folderId`'s key with the server key, or undefined: no such folder, or the keys cannot be used. Never asks who; its callers have. */
+    private folderKey;
+    /** The folders there are, by name: each has its key. */
+    folderNames(): string[];
+    /**
+     * Make shared folder `name` (#2125): its key (`createFolderKey`, which
+     * needs the recovery words confirmed) and its place for pages, sealed with
+     * that key. Admins only (decision 8) until the Shared folders screen
+     * (slice 3). A new folder is opened by admins (`shared-folder-admin`) and
+     * read by executives (`shared-folder-executive-read`), and by nobody else
+     * until a policy names `shared/<name>`; `default` is shipped open to every
+     * signed-in user.
+     * Recorded as `shared-folder-create` before anything is made (on-failure
+     * refuse). Refused when it exists.
+     */
+    createFolder(ctx: ActorContext, name: string): Promise<void>;
+    /**
+     * Make the shipped folders (`SHIPPED_SHARED_FOLDERS`: `/shared/default` and
+     * `/shared/executive`) that are not there yet, once they can be made: the
+     * recovery words are confirmed. Finishing the words does this, and so does
+     * every start (`ensureShippedFoldersAtBoot`), so a site that confirmed its
+     * words before a shipped folder existed gets it on its next start.
+     * Idempotent. Returns the folders made now.
+     */
+    ensureShippedFolders(ctx: ActorContext): Promise<string[]>;
+    /**
+     * At start, make the shipped folders a site with confirmed words does not
+     * have yet (#2095), under the system context. Best-effort: a failure is
+     * logged and never blocks start-up; nothing is tried while the keys cannot
+     * be used.
+     */
+    ensureShippedFoldersAtBoot(): Promise<void>;
+    /**
+     * May `ctx` do `action` (a page or file action, or `shared-folder-read` /
+     * `shared-folder-file`) in folder `name`? The PDP's answer
+     * (`permitsInSharedFolder`); false for a folder that does not exist.
+     */
+    mayInFolder(ctx: ActorContext, action: string, name: string): Promise<boolean>;
+    /**
+     * The folders `ctx` may open (`shared-folder-read`), by name. Asking opens
+     * each one's key to this context (`sharedFolderKeyFor`), so the page and
+     * file doors can read what this reader may. The session middleware asks it
+     * on every request, so a grant removed ends access on the next request
+     * (decision 5).
+     */
+    foldersReadableBy(ctx: ActorContext): Promise<string[]>;
+    /**
+     * Record that `ctx` opened `what` (a page, its history, or a file) in
+     * folder `name` (`shared-folder-read`, on by default: every read of a
+     * shared folder is recorded, #1775). Called by what serves it, after the
+     * door allowed it. The writes are recorded by the page and file doors.
+     */
+    recordRead(ctx: ActorContext, name: string, what: {
+        page?: string;
+        attachmentId?: string;
+        action?: string;
+    }): Promise<void>;
+    /**
+     * Who may read and who may file in folder `name`, as the Shared folders
+     * screen set it: the roles its own policies (`shared-folder-access-<name>-read`
+     * / `-file`, in the site's custom configuration, in the shape the screen
+     * writes) name, and every other policy in force that reaches the folder,
+     * shown as it is, matched as PolicyEvaluator matches it. A policy with one of
+     * the screen's ids that the screen did not write is shown, marked
+     * `reserved`. `admin-system`, as the screen is. Display only: the PDP
+     * decides every access.
+     */
+    folderAccess(ctx: ActorContext, name: string): Promise<SharedFolderAccess & {
+        others: SharedFolderOtherPolicy[];
+    }>;
+    /** The roles a folder's access may name: every role there is but `anonymous`, by name. */
+    grantableRoles(): string[];
+    /**
+     * Set who may read and who may file in folder `name` (#2126, decision 8):
+     * writes the site's policies `shared-folder-access-<name>-read` (granting
+     * `shared-folder-read` on `shared/<name>`) and `-file` (`shared-folder-file`)
+     * to the roles given, through ConfigurationManager, and removes one whose
+     * list is empty. `admin-system`, with a fresh sign-in (the step-up
+     * permission, as every other configuration write asks). Refused for a folder
+     * that does not exist, a role that does not exist, `anonymous` (a folder is
+     * never public), and a folder one of whose ids holds a policy the screen did
+     * not write (it is never overwritten). Recorded as
+     * `shared-folder-access-change` (who, the folder, the roles before and
+     * after) once the write has succeeded; a failed write is recorded as a
+     * failure, and a record that cannot be written puts the policies back
+     * (on-failure refuse). ConfigurationManager records the configuration
+     * change as well. Nothing is written or recorded when nothing changes.
+     * Returns whether it changed.
+     *
+     * Only the screen's own policies change: a shipped or add-on policy, or one
+     * the site wrote elsewhere, still applies (`folderAccess` shows them).
+     */
+    setFolderAccess(ctx: ActorContext, name: string, access: SharedFolderAccess): Promise<boolean>;
+    /**
+     * Folder `name`'s access as the screen sees it: the screen's own policies
+     * (the site's entry under each id, in the shape `accessPolicy` writes), the
+     * ids holding a policy the screen did not write (the site's in another
+     * shape, a deny say, or one in force from a shipped or add-on layer), and
+     * the policies in force.
+     */
+    private accessState;
+    /** The site's own entries of the access policies (the custom configuration layer), as they are: never the shipped or an add-on's. */
+    private siteAccessPolicies;
+    /** The pages directory and the configured vault layout, where folders are kept. */
+    private pagesPlace;
+    /**
+     * Folder `folderId`'s key, opened with the recovery words instead of the
+     * server key: what recovery after a lost server key will use (a later
+     * slice: a new server key, every folder key rewrapped). Throws when the
+     * words are wrong. Works with no server key at all.
+     */
+    openFolderKeyWithWords(ctx: ActorContext, folderId: string, words: string): Promise<Buffer>;
+    private requireAdmin;
+    /**
+     * The fresh sign-in a new set of words (#2144) and an access change (#2126)
+     * need: the PDP applies step-up to `FRESH_SIGN_IN_PERMISSION`, and never
+     * grants it to a delegated credential (an agent token).
+     */
+    private requireFreshSignIn;
+    /** The wrap key, or throws why there is none to use. */
+    private requireUsable;
+    private pendingMinutes;
+    private fileOrNew;
+    private keysPath;
+    private readKeysFile;
+    /** Owner-only, written whole and renamed into place, so a crash never leaves half a file. */
+    private writeKeysFile;
+}
+export default SharedFolderManager;

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

@@ -407,8 +407,11 @@ declare class ValidationManager extends BaseManager {
     /**
      * Check for conflicts with existing pages (duplicate title, slug, or UUID mismatch).
      *
-     * Used when saving a new page or comparing required-pages sources against live pages.
-     * Checks slug first (most precise), then title.
+     * Used when saving a page and when comparing shipped pages (required pages,
+     * add-on pages) against live pages. Checks slug first (most precise), then
+     * title. A name clashes only when another page holds exactly that title or
+     * slug (`PageManager.uuidHoldingName`), never by the plural or fuzzy
+     * matching a link uses (#2140).
      *
      * @async
      * @param {string} uuid - The UUID of the page being checked

package/lib/src/middleware/csrf.js

@@ -0,0 +1,99 @@
+/**
+ * App-wide CSRF middleware (#663).
+ *
+ * Issues a per-session token at session start and validates it on every
+ * state-changing request. Token lives at `req.session.csrfToken` and is
+ * surfaced to templates as `csrfToken` via `getCommonTemplateData()`.
+ *
+ * Submission channels:
+ *   - HTML forms: hidden `<input name="_csrf" value="<%= csrfToken %>">`
+ *   - JS-driven fetches: `X-CSRF-Token` request header
+ *
+ * Safe methods (GET/HEAD/OPTIONS) pass through unchecked but still trigger
+ * lazy token issuance, so the very first response can already render the
+ * token in any form. Mismatches return HTTP 403 with a plain-text body and
+ * a logger.warn that captures method, path, ip, and which side was missing.
+ * When the cause is a secure session cookie on a plain-http request, the
+ * body says so in plain words (#2071).
+ *
+ * Token comparison uses `crypto.timingSafeEqual` after a length-equal guard
+ * so neither presence nor length leaks via response timing.
+ */
+import { randomBytes, timingSafeEqual } from 'crypto';
+import logger from '../utils/logger.js';
+import { sessionCookieWithheld, SESSION_COOKIE_WITHHELD_MESSAGE } from '../utils/sessionSecurity.js';
+const TOKEN_BYTES = 32;
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const HEADER_NAME = 'x-csrf-token';
+const BODY_FIELD = '_csrf';
+export function generateCsrfToken() {
+    return randomBytes(TOKEN_BYTES).toString('hex');
+}
+function constantTimeEquals(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string')
+        return false;
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+function readSubmittedToken(req) {
+    const header = req.get(HEADER_NAME);
+    if (typeof header === 'string' && header.length > 0)
+        return header;
+    const body = req.body?.[BODY_FIELD];
+    return typeof body === 'string' && body.length > 0 ? body : undefined;
+}
+export function csrfMiddleware(req, res, next) {
+    if (req.session && !req.session.csrfToken) {
+        req.session.csrfToken = generateCsrfToken();
+        // Force a sync save before the response goes out. Otherwise the file-
+        // store write can lag behind the Set-Cookie header reaching the client,
+        // and a fast follow-up POST (typical in parallel E2E browsers) hits
+        // before the session file lands on disk — server creates a fresh
+        // session with a different token, CSRF check fails. Pay the latency
+        // cost once on first request per session; cheap on subsequent ones
+        // because the if-guard skips this branch.
+        if (typeof req.session.save === 'function') {
+            req.session.save(() => continueAfterSave(req, res, next));
+            return;
+        }
+    }
+    continueAfterSave(req, res, next);
+}
+function continueAfterSave(req, res, next) {
+    if (SAFE_METHODS.has(req.method)) {
+        next();
+        return;
+    }
+    // #818 — token-authenticated API requests are exempt. The request-credential
+    // middleware sets `req.bearerAuth` after AuthManager verifies the token
+    // (a Bearer header, or Dawarich's agent token in x-api-key, #1759); such requests
+    // carry no session cookie, so CSRF (a cookie-confused-deputy defense) does
+    // not apply. Cookie/session-authenticated POSTs still require the token.
+    if (req.bearerAuth === true) {
+        next();
+        return;
+    }
+    const expected = req.session?.csrfToken;
+    const submitted = readSubmittedToken(req);
+    if (typeof expected !== 'string' ||
+        typeof submitted !== 'string' ||
+        !constantTimeEquals(expected, submitted)) {
+        const expectedState = expected ? 'present' : 'missing';
+        const submittedState = submitted ? 'present' : 'missing';
+        // #2071: a secure cookie on a plain-http request never reached the
+        // browser, so no token could match. Say so, rather than only "invalid".
+        const withheld = sessionCookieWithheld(req);
+        logger.warn(`[csrf] rejected ${req.method} ${req.path} from ${req.ip ?? 'unknown'} — ` +
+            `expected:${expectedState} submitted:${submittedState}` +
+            (withheld ? ' (the session cookie is secure and this request is plain http, #2071)' : ''));
+        res
+            .status(403)
+            .type('text/plain')
+            .send(withheld
+            ? `Forbidden — invalid CSRF token. ${SESSION_COOKIE_WITHHELD_MESSAGE}`
+            : 'Forbidden — invalid CSRF token');
+        return;
+    }
+    next();
+}

package/lib/src/providers/AgentTokenAuthProvider.js

@@ -0,0 +1,46 @@
+/**
+ * AgentTokenAuthProvider — verify a user-delegated agent API token presented
+ * on the `Authorization: Bearer <token>` header (#946).
+ *
+ * Counterpart to AuthentikBearerAuthProvider, but with no external IdP: the
+ * credential is minted in-app by the user it belongs to. Both providers can be
+ * enabled at once — the bearer middleware tries each registered bearer-capable
+ * provider in turn.
+ *
+ * The provider only answers "which user, and with which scopes". Permissions
+ * are resolved live from that user's record by the middleware, so a token
+ * never carries a snapshot of its owner's authority.
+ *
+ * Wire-up: request-time middleware in `src/app.ts` (header → verify →
+ * set req.userContext). Stateless — no session is created for API calls. It
+ * does NOT participate in the /login flow.
+ */
+import logger from '../utils/logger.js';
+export class AgentTokenAuthProvider {
+    id = 'agent-token';
+    displayName = 'Agent API Token';
+    /** Marks this provider as usable by the bearer middleware. */
+    acceptsBearer = true;
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async verify(credentials) {
+        const token = credentials?.token;
+        if (typeof token !== 'string' || token.length === 0)
+            return null;
+        const manager = this.engine.getManager('AgentTokenManager');
+        if (!manager) {
+            logger.warn('[agent-token] AgentTokenManager not available — cannot verify');
+            return null;
+        }
+        const record = await manager.verify(token);
+        if (!record)
+            return null;
+        return {
+            username: record.owner,
+            viaToken: { id: record.id, name: record.name, scopes: record.scopes }
+        };
+    }
+}
+export default AgentTokenAuthProvider;

package/lib/src/providers/AuthentikBearerAuthProvider.js

@@ -0,0 +1,176 @@
+/**
+ * AuthentikBearerAuthProvider — verify an Authentik-issued OAuth/OIDC bearer
+ * JWT presented on the `Authorization: Bearer <token>` header (#818).
+ *
+ * Unlike the interactive Google-OIDC code-exchange flow, this provider trusts
+ * a token an automated client (e.g. an AI agent) already holds — minted in
+ * Authentik via the `client_credentials` grant against a per-person service
+ * account. It verifies the JWT signature against Authentik's JWKS, checks
+ * issuer + audience, then coordinates the identity to a local User record.
+ *
+ * Design mirrors CloudflareAccessAuthProvider (#649):
+ *  - User coordination by **email** (`email` claim).
+ *  - Unknown user → **JIT-provision** with default-role (overridable per
+ *    Authentik group via `group-map`).
+ *  - `groups[]` claim → ngdpbase roles via config-map.
+ *
+ * Author attribution (epic decision A): the service account's email is set to
+ * match the human's ngdpbase account, so `findUserByEmail` resolves to that
+ * user and pages are authored under their existing username (the UI renders
+ * their displayName, e.g. "Jim Willeke").
+ *
+ * Wire-up: invoked by the request-time middleware in `src/app.ts` (header →
+ * verify → resolve-or-provision → set req.userContext, stateless — no session
+ * is created for API calls). It does NOT participate in the /login flow.
+ *
+ * Token verification uses `jose.createRemoteJWKSet` against the configured
+ * JWKS URL — keys are fetched on demand and cached + rotated by jose.
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { jobContextFromRequestWithReason } from '../context/JobContext.js';
+import { systemPrincipalOf } from '../context/bootActions.js';
+import logger from '../utils/logger.js';
+import { emailDomain } from '../utils/emailForLog.js';
+export class AuthentikBearerAuthProvider {
+    id = 'authentik-bearer';
+    displayName = 'Authentik (Bearer)';
+    /** Marks this provider as usable by the bearer middleware. */
+    acceptsBearer = true;
+    engine;
+    config;
+    jwks;
+    /**
+     * @param jwksOverride optional pre-built JWKS getter for tests; production
+     *   omits this and uses `createRemoteJWKSet` against the configured JWKS URL.
+     */
+    constructor(engine, config, jwksOverride) {
+        this.engine = engine;
+        this.config = config;
+        this.jwks = jwksOverride ?? createRemoteJWKSet(new URL(config.jwksUrl));
+    }
+    /**
+     * Verify the bearer JWT and resolve (or provision) the local user.
+     * `credentials.token` is the raw JWT lifted from the `Authorization: Bearer`
+     * header by the request-time middleware.
+     */
+    async verify(credentials) {
+        const token = credentials.token;
+        if (!token) {
+            return null;
+        }
+        // The bearer middleware offers every bearer token to every bearer
+        // provider in turn, so this one routinely sees credentials that belong to
+        // another provider (an `ngdp_at_` agent token, an opaque OIDC token). A
+        // token that is not a compact JWS (three dot-separated segments) cannot be
+        // an Authentik JWT: decline it quietly. The result is the same `null`
+        // jwtVerify would give — nothing is accepted that was refused before —
+        // only the warn line, which fired on every agent-token request, goes.
+        // JWT-shaped tokens that fail verification still warn below.
+        if (token.split('.').length !== 3) {
+            logger.debug('[AuthentikBearerAuthProvider] bearer token is not a JWT — not an Authentik credential');
+            return null;
+        }
+        let verified;
+        try {
+            verified = await jwtVerify(token, this.jwks, {
+                issuer: this.config.issuer,
+                audience: this.config.audience
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Surface the underlying cause (e.g. JWKS fetch network errors like
+            // ECONNREFUSED / EHOSTUNREACH / ENOTFOUND) — "fetch failed" alone is opaque.
+            const cause = (err && typeof err === 'object' && 'cause' in err)
+                ? err.cause
+                : undefined;
+            const causeStr = cause
+                ? ` (cause: ${cause.code ?? ''} ${cause.message ?? ''})`.trimEnd()
+                : '';
+            logger.warn(`[AuthentikBearerAuthProvider] JWT verification failed: ${message}${causeStr}`);
+            return null;
+        }
+        const payload = verified.payload;
+        const email = payload.email?.toLowerCase();
+        if (!email) {
+            logger.warn('[AuthentikBearerAuthProvider] JWT had no email claim');
+            return null;
+        }
+        return this.resolveOrProvision(email, payload);
+    }
+    async resolveOrProvision(email, payload) {
+        const userManager = this.engine.getManager('UserManager');
+        if (!userManager) {
+            logger.error('[AuthentikBearerAuthProvider] UserManager unavailable');
+            return null;
+        }
+        // Email-keyed lookup. Resolving to the human's existing account is the
+        // mechanism behind decision A (author reads as the human).
+        // #2073: an email several accounts share is refused, never guessed between
+        // and never given a new account: a gateway's header cannot ask which.
+        const holders = await userManager.getUsersByEmail(email);
+        if (holders.length > 1) {
+            logger.warn(`[AuthentikBearerAuthProvider] ${holders.length} accounts share an address at ${emailDomain(email)}; refused, since a gateway sign-in cannot ask which (#2073)`);
+            return null;
+        }
+        const existing = holders[0];
+        if (existing) {
+            logger.info(`[AuthentikBearerAuthProvider] Existing user matched: ${existing.username}`);
+            return { username: existing.username };
+        }
+        // JIT-provision. Username derived from a name claim or email local-part.
+        const desiredUsername = payload.preferred_username || email.split('@')[0];
+        const username = await this.deriveUniqueUsername(userManager, desiredUsername);
+        const displayName = payload.name || payload.preferred_username || username;
+        const roles = this.mapGroupsToRoles(payload.groups ?? []);
+        try {
+            const created = await userManager.createUser({
+                username,
+                email,
+                displayName,
+                // Federated users have no local password — mirrors GoogleOIDC / CF.
+                password: '',
+                roles,
+                isExternal: true,
+                isActive: true
+            }, jobContextFromRequestWithReason({ username: systemPrincipalOf(this.engine) }, 'provisioned by authentik-bearer')); // #1204: provisioned, not registered; #1179: the system principal acts, the reason names the provider
+            logger.info(`[AuthentikBearerAuthProvider] JIT-provisioned user: ${username} (an address at ${emailDomain(email)}) with roles=[${roles.join(', ')}]`);
+            return { username: created.username }; // #1882: the account as stored
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`[AuthentikBearerAuthProvider] JIT provision failed for ${username}:`, message);
+            return null;
+        }
+    }
+    /**
+     * Map Authentik groups[] to ngdpbase role names. Groups without an entry in
+     * config.groupMap are dropped silently. Result always contains
+     * config.defaultRole — even with no group hits, user gets the default.
+     */
+    mapGroupsToRoles(groups) {
+        const out = new Set([this.config.defaultRole]);
+        for (const g of groups) {
+            const mapped = this.config.groupMap[g];
+            if (mapped)
+                out.add(mapped);
+        }
+        return Array.from(out);
+    }
+    async deriveUniqueUsername(userManager, desired) {
+        const getUser = userManager.getUser;
+        if (typeof getUser !== 'function')
+            return desired;
+        let candidate = desired;
+        let suffix = 1;
+        // Cap at a sane number — defensive only; collisions are rare in practice.
+        while (suffix < 100) {
+            const existing = await getUser.call(userManager, candidate);
+            if (!existing)
+                return candidate;
+            candidate = `${desired}${suffix}`;
+            suffix++;
+        }
+        return `${desired}-${Date.now()}`;
+    }
+}