@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/providers/OidcBearerAuthProvider.js

@@ -0,0 +1,27 @@
+export class OidcBearerAuthProvider {
+    engine;
+    id = 'oidc-bearer';
+    displayName = 'OpenID Connect access token';
+    /** Marks this provider as usable by the bearer middleware. */
+    acceptsBearer = true;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async verify(credentials) {
+        const token = credentials?.token;
+        if (typeof token !== 'string' || token.length === 0)
+            return null;
+        const oidc = this.engine.getManager('OidcManager');
+        const verified = await oidc?.verifyAccessToken(token);
+        if (!verified)
+            return null;
+        const name = await oidc.clientName(verified.clientId);
+        return {
+            username: verified.username,
+            // The grant, not the token: a token rotates; the grant is what the person allowed.
+            viaToken: { id: `oidc:${verified.grantId}`, name, scopes: verified.scopes },
+            aal: verified.aal
+        };
+    }
+}
+export default OidcBearerAuthProvider;

package/lib/src/providers/PasskeyAuthProvider.js

@@ -0,0 +1,147 @@
+/**
+ * Passkeys — WebAuthn (#448), on `@simplewebauthn/server` directly (decided
+ * 2026-10-03; not activescott's provider, which needs its JWT session layer).
+ *
+ * A passkey alone signs a person in (NIST SP 800-63B: a multi-factor
+ * cryptographic authenticator suffices for AAL2), and it is phishing-resistant:
+ * the browser signs only for the relying party it was created for.
+ *
+ * - The relying party is the host of `ngdpbase.application.base-url`, never the
+ *   request, so a passkey works only on that hostname. AuthManager registers
+ *   this provider only when base-url is set explicitly and is a secure context
+ *   (https, or localhost).
+ * - Passkeys live in the credentials store (#1524), kind `passkey`: the
+ *   subject is the credential id, the secret the public key and its counter.
+ *   AuthManager hands this provider two narrow functions for that, so the
+ *   store keeps one owner.
+ * - The challenge is single-use and kept server-side by the caller (the
+ *   session); this provider only generates options and verifies responses.
+ */
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import logger from '../utils/logger.js';
+/** The base-url origin, its host, and whether WebAuthn may run there (https, or localhost). */
+export function relyingPartyFrom(baseUrl, rpName) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return null;
+    }
+    const local = url.hostname === 'localhost' || url.hostname.endsWith('.localhost');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+        return null;
+    return { rpID: url.hostname, origin: url.origin, rpName };
+}
+function parseSecret(secret) {
+    try {
+        const s = JSON.parse(secret);
+        return typeof s.publicKey === 'string' && typeof s.counter === 'number' ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class PasskeyAuthProvider {
+    rp;
+    store;
+    id = 'passkey';
+    displayName = 'Passkey';
+    /**
+     * Something you have (the key) unlocked by something you know or are (the
+     * PIN or biometric the authenticator requires): AAL2, phishing-resistant.
+     * `swk` because most passkeys sync; a device-bound key is stronger, never
+     * weaker, than what is claimed here.
+     */
+    factor = { amr: ['swk', 'user'], aal: 2, acr: 'phr', primary: true };
+    constructor(rp, store) {
+        this.rp = rp;
+        this.store = store;
+    }
+    /** The relying party passkeys are tied to — for the admin page and the enrol screen. */
+    relyingParty() {
+        return { ...this.rp };
+    }
+    /** Options for enrolling a passkey; `existing` keeps one authenticator from enrolling twice. */
+    async registrationOptions(username, displayName, existing) {
+        return generateRegistrationOptions({
+            rpName: this.rp.rpName,
+            rpID: this.rp.rpID,
+            userName: username,
+            userDisplayName: displayName || username,
+            attestationType: 'none',
+            excludeCredentials: existing.map(c => ({ id: c.subject, transports: parseSecret(c.secret)?.transports })),
+            authenticatorSelection: { residentKey: 'required', userVerification: 'required' }
+        });
+    }
+    /** Verify an enrolment; returns what the credentials store keeps, or null when it does not verify. */
+    async verifyRegistration(response, expectedChallenge) {
+        try {
+            const result = await verifyRegistrationResponse({
+                response,
+                expectedChallenge,
+                expectedOrigin: this.rp.origin,
+                expectedRPID: this.rp.rpID,
+                requireUserVerification: true
+            });
+            if (!result.verified)
+                return null;
+            const info = result.registrationInfo;
+            const secret = {
+                publicKey: Buffer.from(info.credential.publicKey).toString('base64url'),
+                counter: info.credential.counter,
+                transports: info.credential.transports,
+                deviceType: info.credentialDeviceType,
+                backedUp: info.credentialBackedUp
+            };
+            return { subject: info.credential.id, secret: JSON.stringify(secret) };
+        }
+        catch (err) {
+            logger.warn(`[Passkey] enrolment did not verify: ${err.message}`);
+            return null;
+        }
+    }
+    /** Options for signing in: no username asked, any passkey for this host may answer. */
+    async authenticationOptions() {
+        return generateAuthenticationOptions({ rpID: this.rp.rpID, userVerification: 'required' });
+    }
+    /**
+     * Verify a sign-in. The credential id names the passkey; its public key and
+     * counter come from the store. A counter that does not move forward (where
+     * the authenticator keeps one) is a cloned key and fails.
+     */
+    async verify(credentials) {
+        const assertion = credentials.webauthn;
+        if (!assertion)
+            return null;
+        const response = assertion.response;
+        const row = typeof response?.id === 'string' ? this.store.find(response.id) : null;
+        const secret = row ? parseSecret(row.secret) : null;
+        if (!row || !secret)
+            return null;
+        try {
+            const result = await verifyAuthenticationResponse({
+                response,
+                expectedChallenge: assertion.expectedChallenge,
+                expectedOrigin: this.rp.origin,
+                expectedRPID: this.rp.rpID,
+                credential: {
+                    id: row.subject,
+                    publicKey: new Uint8Array(Buffer.from(secret.publicKey, 'base64url')),
+                    counter: secret.counter,
+                    transports: secret.transports
+                },
+                requireUserVerification: true
+            });
+            if (!result.verified)
+                return null;
+            const next = { ...secret, counter: result.authenticationInfo.newCounter, backedUp: result.authenticationInfo.credentialBackedUp };
+            await this.store.used(row.id, new Date().toISOString(), JSON.stringify(next));
+            return { username: row.username };
+        }
+        catch (err) {
+            logger.warn(`[Passkey] sign-in did not verify for credential ${row.id}: ${err.message}`);
+            return null;
+        }
+    }
+}

package/lib/src/providers/PasswordAuthProvider.js

@@ -0,0 +1,44 @@
+/**
+ * PasswordAuthProvider — username/password authentication.
+ *
+ * The password method's check (#1758): AuthManager is the one door for every
+ * check of a secret, and this provider is its connection to the password.
+ * The hash stays on the account (UserManager keeps it and hands it only to
+ * this check); the check, and the decision to re-hash at the current cost
+ * (#1042), are made here. Registered by AuthManager as the default provider.
+ */
+import { hashPassword, verifyPassword, needsRehash, isLegacyHash } from '../utils/passwordHash.js';
+export class PasswordAuthProvider {
+    engine;
+    id = 'password';
+    displayName = 'Username & Password';
+    /** Something you know (#1523). */
+    factor = { amr: ['pwd'], aal: 1, primary: true };
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async verify(credentials) {
+        const { username, password } = credentials;
+        if (!username || !password)
+            return null;
+        const userManager = this.engine.getManager('UserManager');
+        if (!userManager)
+            return null;
+        const stored = await userManager.storedPasswordHash(username);
+        if (!stored)
+            return null;
+        // The legacy salt keeps its historic value: legacy digests were made with it (#1042).
+        const legacySalt = this.engine.getManager('ConfigurationManager')
+            ?.getProperty('ngdpbase.user.security.passwordsalt', 'amdwiki-salt');
+        if (!(await verifyPassword(password, stored, legacySalt || 'amdwiki-salt')))
+            return null;
+        // #1882: the account as stored, never the casing typed — lookups ignore case (#1436).
+        const account = await userManager.getUser(username);
+        if (!account?.username)
+            return null;
+        // #1042: upgrade the stored hash now, while the plaintext is known to be right.
+        if (needsRehash(stored))
+            await userManager.upgradePasswordHash(account.username, await hashPassword(password), isLegacyHash(stored));
+        return { username: account.username };
+    }
+}

package/lib/src/security/PolicyDecisionPoint.d.ts

@@ -131,9 +131,10 @@ export declare class PolicyDecisionPoint extends BaseManager {
      * {@link permits}, which is "may it act now", and named so: an affordance
      * (show the reveal button, show the sign-in methods section) asks this, so a
      * person whose sign-in is not fresh still sees the way to the prompt that
-     * makes it fresh. A door never asks this.
+     * makes it fresh. A door never asks this. `on` asks it about a resource,
+     * as {@link decide} does (#2120: a vault page's export).
      */
-    holds(subject: DecisionInput, action: string): Promise<boolean>;
+    holds(subject: DecisionInput, action: string, on?: Omit<DecisionRequest, 'action'>): Promise<boolean>;
     /**
      * Step-up (#1525, #1635), decided here — in the one place every door asks —
      * rather than by routes in front of the doors. A permission marked

package/lib/src/security/pageActions.js

@@ -0,0 +1,43 @@
+'use strict';
+/**
+ * One vocabulary for page actions (#1431, step 5).
+ *
+ * A door asks for a PERMISSION, and every permission name is declared in
+ * `ngdpbase.permissions.definitions`. Page-level checks grew their own words
+ * anyway — `canAccess('view')`, `canAccess('edit')` — which are declared
+ * nowhere, and `PolicyInformationPoint.checkDefaultPermission` invented a third set with
+ * colons (`page:read`), declared nowhere either, so that check could only ever
+ * deny ([#1174](https://github.com/jwilleke/ngdpbase/issues/1174)).
+ *
+ * This is the one translation: the short word a caller passes, mapped to the
+ * registry name policy is written in. It exists so the mapping is not
+ * copied — it was already in `checkPagePermissionWithContext` twice, and in
+ * `checkDefaultPermission` in a different and broken form.
+ *
+ * New code should pass the registry name directly. The short forms stay
+ * because they are what a page author writes in `[{ALLOW view …}]` ACL markup,
+ * and that is a content syntax, not an internal vocabulary.
+ */
+/** The short words accepted at a page door, and in ACL markup. */
+export const PAGE_ACTION_ALIASES = {
+    view: 'page-read',
+    read: 'page-read',
+    edit: 'page-edit',
+    delete: 'page-delete',
+    create: 'page-create',
+    rename: 'page-rename',
+    export: 'page-export',
+    upload: 'asset-upload'
+};
+/**
+ * The registry permission a page action means.
+ *
+ * An unknown word is returned unchanged rather than guessed at: it is either
+ * already a registry name — which is what new code passes — or it is a typo,
+ * and the permission-registry invariant is what catches a typo, not a silent
+ * rewrite into `page:<whatever>` (which is what the deleted code did).
+ */
+export function permissionForPageAction(action) {
+    const key = action.trim().toLowerCase();
+    return PAGE_ACTION_ALIASES[key] ?? key;
+}

package/lib/src/security/permissions.generated.d.ts

@@ -1,6 +1,6 @@
 /** Every permission core declares. Addons generate their own union. */
 export type CorePermission = 
-/** Change what protects your own account — password, email, sign-in methods (passkeys), vault takeout and import, approving a device (#1525). Granted wherever profile-manage is; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
+/** Change what protects your own account — password, email, sign-in methods (passkeys), vault takeout and import, approving a device (#1525). Granted wherever profile-manage is; asks for a fresh sign-in, because the entry carries "step-up": true (#1638) */
 'account-security'
 /** View administration screens (read-only, no changes) */
  | 'admin-read'
@@ -20,7 +20,7 @@ export type CorePermission =
  | 'audit-export'
 /** Add a comment, and delete your own; deleting anyone's is admin-system (#1198) */
  | 'comment-create'
-/** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
+/** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in, because the entry carries "step-up": true (#1638) */
  | 'config-manage'
 /** Open the Executive Hub (/executive): the organization's summary cards and the requests waiting for the board (#2093). Held by the executive role; deciding a request still needs that request's own permission */
  | 'executive-read'
@@ -54,7 +54,7 @@ export type CorePermission =
  | 'search-page'
 /** Search users */
  | 'search-user'
-/** Unmask a configuration secret (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up. Hashed credentials (agent tokens) and shown-once secrets can never be revealed */
+/** Unmask a configuration secret (#1525). Admin only by default; asks for a fresh sign-in, because the entry carries "step-up": true (#1638). Hashed credentials (agent tokens) and shown-once secrets can never be revealed */
  | 'secret-reveal'
 /** End another person's signed-in session (#1638) */
  | 'session-revoke'
@@ -64,6 +64,10 @@ export type CorePermission =
  | 'share-extend'
 /** Revoke your own share links; revoking anyone's also needs admin-system (#1638) */
  | 'share-revoke'
+/** Add, edit and delete pages and files in a shared folder (/shared/<name>, #2125). Scoped to one folder by the policy's resource (type shared-folder, pattern shared/<name>). The writes themselves are recorded by the page and file doors (page-create, page-edit, page-delete, asset-upload, asset-delete) */
+ | 'shared-folder-file'
+/** Open a shared folder (/shared/<name>, #2125): its pages, their history and its files. Scoped to one folder by the policy's resource (type shared-folder, pattern shared/<name>); a folder lists no roles. Shipped granted on shared/default to every account, and on every folder (shared/*) to admin */
+ | 'shared-folder-read'
 /** Walk through a private store's door and create your own copy of it — with a user key and recovery words when the store kind is encrypted (#1414). Every signed-in role; never anonymous. The door also needs a password sign-in, so a token or share cannot use it */
  | 'store-create'
 /** Extend your own live agent tokens instead of minting new ones, to at most max-ttl-hours from now; the token and its scopes stay the same (#1734). Admin only by default. A token can never carry this scope */

package/lib/src/types/File.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The file record (#1852, epic #1851): one shape for every file the site
+ * keeps, read through `FileManager`, the one door.
+ *
+ * The decisions behind it are the epic's decision log
+ * (https://github.com/jwilleke/ngdpbase/issues/1851#issuecomment-6236003946);
+ * the practice is docs/guides/storage-developer-guide.md.
+ *
+ * It is not a new vocabulary. `AssetRecord` (src/types/Asset.ts) is already
+ * the internal, schema.org-named shape for a stored file (docs/schemas.md
+ * Decision 11), so the record takes its fields from there by name and adds
+ * only what an asset record does not say: where the file lives, who owns it,
+ * and its system-category. A field that changes in `AssetRecord` changes
+ * here too; there is no second copy to drift.
+ */
+import type { AssetRecord } from './Asset.js';
+/**
+ * Where a file lives: the public area, one user's vault, or one shared
+ * folder. A file is unique by its place plus its name; the same name may
+ * exist in two places.
+ *
+ * Each place is named by the identifiers the site already uses: a vault by
+ * its owner's username and its vault id (`pages/vaults/{owner}/{vault}/`), a
+ * shared folder by its name (`/shared/{folder}`, SharedFolderManager). The
+ * shared folders' internal container (`SHARED_FOLDER_OWNER`) is never a
+ * vault owner here: a folder is always `{ kind: 'shared-folder' }` (#2148).
+ */
+export type FilePlace = {
+    kind: 'public';
+} | {
+    kind: 'vault';
+    owner: string;
+    vault: string;
+} | {
+    kind: 'shared-folder';
+    folder: string;
+};
+/**
+ * One file, as the door shows it.
+ *
+ * From `AssetRecord`, unchanged in meaning:
+ * - `id`: the stable identity, kept across renames and moves.
+ * - `filename`: the file's name, the one links use (`[Annual Report.pdf]`),
+ *   unique within its place.
+ * - `name`: the human title, when one was given (schema.org `name`).
+ * - `description`, `keywords`: descriptive metadata.
+ * - `encodingFormat`: the media type (`application/pdf`, `image/png`…).
+ * - `contentSize`, `url`, `mentions` (the pages that show it).
+ * - `dateCreated` / `author`: when and by whom it was created, as recorded
+ *   (the uploader; a legacy record may say `Unknown`).
+ * - `dateModified` / `editor`: when and by whom it last changed.
+ *
+ * Added here:
+ * - `place`: public, a vault, or a shared folder.
+ * - `owner`: the user it belongs to. A vault's files are the vault owner's.
+ *   A public file's owner is its uploader when the record names a user, or
+ *   `null` when it does not (`Unknown`, empty, an email used as a name):
+ *   the migration gives those an owner from configuration.
+ * - `systemCategory`: the category whose rules apply. Per file, never by
+ *   type. A public file today is the default category's; a vault file is
+ *   the category that declares its vault, or `null` when none does.
+ */
+export type FileRecord = Pick<AssetRecord, 'id' | 'filename' | 'name' | 'description' | 'keywords' | 'encodingFormat' | 'contentSize' | 'url' | 'mentions' | 'dateCreated' | 'author' | 'dateModified' | 'editor'> & {
+    place: FilePlace;
+    owner: string | null;
+    systemCategory: string | null;
+};
+/**
+ * What the operator inventory shows of one vault (#1859's dry run). Counts
+ * only: a vault's names, owners and metadata belong to its owner and never
+ * leave the door. A sealed vault can't be read without its owner's key, so
+ * only what is on disk is counted (bytes as stored, sealed) and its clashes
+ * are unknown (`null`).
+ */
+export interface VaultFileSummary {
+    owner: string;
+    vault: string;
+    systemCategory: string | null;
+    /** Whether its index could be read. False for a sealed vault (no key here) or one refused as not yet opened. */
+    readable: boolean;
+    files: number;
+    bytes: number;
+    /** Files that would get a `-###` suffix in this vault; `null` when it can't be read. */
+    clashes: number | null;
+}
+/** Everything the site keeps as files, for the operator (#1859): the public files in full, each vault as counts. */
+export interface FileInventory {
+    publicFiles: FileRecord[];
+    vaults: VaultFileSummary[];
+}

package/lib/src/types/Provider.d.ts

@@ -342,6 +342,15 @@ export interface PageProvider extends BaseProvider {
      * @returns Canonical page title or null
      */
     findPage(identifier: string): string | null;
+    /**
+     * The uuid of the page that holds `name` as its title, or as its slug (#2140).
+     * This is the store's uniqueness rule: see the provider's implementation.
+     * @param field - Which name: 'title' or 'slug'
+     * @param name - The title or slug
+     * @param ctx - Who is asking: a vault page's title is matched in its vault
+     * @returns The holder's uuid, or null when no page holds it
+     */
+    uuidHoldingName(field: 'title' | 'slug', name: string, ctx: ActorContext): string | null;
     /**
      * Get a page by its UUID
      * @param uuid - Page UUID
@@ -558,6 +567,12 @@ export interface AttachmentMetadata {
     filePath: string;
     /** Description */
     description?: string;
+    /**
+     * True when the store already held these bytes and stored nothing new
+     * (#2130): the record returned is the existing one, under its own name.
+     * Set by `storeAttachment`; absent for a new file.
+     */
+    alreadyHeld?: boolean;
     /** Additional metadata */
     [key: string]: unknown;
 }

package/lib/src/types/express.d.ts

@@ -17,7 +17,7 @@
  */
 import type { ShareGrant } from './Share.js';
 import type { ProxyClaim } from '../managers/UserManager.js';
-import type { SignInRecord, PendingConnection, OutsideChoice } from '../managers/AuthManager.js';
+import type { SignInRecord, PendingConnection, OutsideChoice, PendingStepUp, StepUpPrompt } from '../managers/AuthManager.js';
 declare module 'express-session' {
     interface SessionData {
         csrfToken?: string;
@@ -40,6 +40,12 @@ declare module 'express-session' {
             purpose: 'register' | 'authenticate' | 'reauth';
             expires: number;
         };
+        /** The step-up asked for and not yet given (#2145): its permission, where it returns, whether returning redoes it. */
+        pendingStepUp?: PendingStepUp;
+        /** The path whose next page view says "Confirmed — you can do it now" after a step-up (#2145). */
+        stepUpConfirmed?: string;
+        /** A script's step-up prompts (#2193), the newest few: each id and whether it was confirmed or cancelled. */
+        stepUpPrompts?: StepUpPrompt[];
         /** A sign-in waiting for its second factor: the handle, and where to go after (#1523). No identity yet. */
         pendingSignIn?: string;
         pendingRedirect?: string;