@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,480 @@
+import BaseManager, { BackupData } from './BaseManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+import { UserProvider } from '../types/Provider.js';
+import { User, UserPreferences, UserSession } from '../types/User.js';
+import type { ShareGrant } from '../types/Share.js';
+/**
+ * The agent token a request arrived with (#946).
+ *
+ * Declared rather than reached by a cast (#1164). `hasPermission` used to read
+ * `viaToken` off a parameter typed `{ username; roles; isAuthenticated }` — a
+ * field the declared type did not mention. That is not a detail: the type
+ * described a three-field object, so satisfying it by BUILDING one was the
+ * obvious thing to do, and any object built that way silently carries no token
+ * for the ceiling to find. `AttachmentManager` did exactly that and bypassed
+ * the ceiling on the path that looked safe.
+ */
+export interface AgentTokenGrant {
+    id: string;
+    name: string;
+    scopes: string[];
+}
+/**
+ * A person acting for another under a proxy grant (#1762 slice 2), as a
+ * subject carries it. The subject's `username` and `roles` are the person
+ * REPRESENTED; this names who is actually acting and under which grant.
+ *
+ * The PDP re-reads the grant on every decision (`AuthManager.liveProxyGrant`)
+ * — nothing here is trusted beyond naming it — and bounds the action by the
+ * grant's permissions and by what `actor` holds, live. A proxy is not a
+ * delegated credential for step-up: the actor's own fresh sign-in counts, so
+ * the subject's `signIn` and `aalCap` are the ACTOR's (the session's).
+ *
+ * `kind: 'impersonation'` is reserved for #1763 "view as"; nothing admits it
+ * yet, so a subject carrying it is refused everywhere.
+ */
+export interface ProxyClaim {
+    kind: 'proxy' | 'impersonation';
+    /** The grant's id in the credentials store. */
+    grantId: string;
+    /** Who is acting: the grant's proxy. */
+    actor: string;
+    /** The grant's permissions as the subject was built with them; the live grant must still carry every one. */
+    scopes: string[];
+    /**
+     * The actor's OWN private-store handle (#1762 slice 5): where a key copy
+     * opened under this grant is held (`privateStoreUnlock.openKeyCopy`). It
+     * reaches only that copy — never the actor's own keys — and only while the
+     * copy was opened for this grant and this represented person (`dekFor`).
+     */
+    keyHandle?: string;
+}
+/**
+ * The subject for a check about nobody in particular (#1164).
+ *
+ * There is one honest reason to hand `hasPermission` a subject you built:
+ * asking what an ANONYMOUS visitor may do, where there is no user and no token
+ * by definition. Naming it once keeps that case explicit and keeps
+ * `check-permission-subject.ts` free to reject every inline literal — an
+ * escape hatch nobody can reach by accident.
+ */
+export declare const ANONYMOUS_SUBJECT: PermissionSubject;
+/** Config key naming the system principal. Ships as `$NGDPBASE_SYSTEM_USER` — env-owned, bare form (#631). */
+export declare const SYSTEM_PRINCIPAL_KEY = "ngdpbase.system.principal";
+/** Config key listing the roles the system principal holds. Ships as `["admin"]` (#631). */
+export declare const SYSTEM_ROLES_KEY = "ngdpbase.system.roles";
+/**
+ * Who a permission check is about.
+ *
+ * __Forward the context you were given; do not rebuild one.__ `viaToken` is
+ * optional because an ordinary session request has none — which means the type
+ * cannot force you to carry it. Rebuilding a subject from parts therefore still
+ * compiles, and still drops the ceiling. What stops that is
+ * `scripts/check-permission-subject.ts`, not the compiler.
+ */
+export interface PermissionSubject {
+    username: string;
+    roles: string[];
+    isAuthenticated: boolean;
+    /** Present only when the request authenticated with an agent token. */
+    viaToken?: AgentTokenGrant;
+    /** Present only when the request presented a share token (#1222). Forwarded like `viaToken`. */
+    viaShare?: ShareGrant;
+    /**
+     * Present only when someone is acting for this subject's person under a
+     * proxy grant (#1762). Forwarded like `viaToken`; never combined with a
+     * token or a share (the PDP refuses a subject carrying both).
+     */
+    viaProxy?: ProxyClaim;
+    /** The address the request came from (#1179) — provenance for the record, set where the request subject is built. */
+    ipAddress?: string;
+    /**
+     * Opaque handle to this session's unlocked private-store keys (#1382).
+     * Random — not the session id — created at password login and dropped at
+     * logout; resolved live, so after logout it reaches nothing. Set only where
+     * the request subject is built; never recorded (`actorOf` must not gain it).
+     */
+    privateStoreHandle?: string;
+    /**
+     * How and when this session signed in (#1525, #1635): the factors and when
+     * each was last satisfied. Set only where the request subject is built from
+     * the session, so the PDP can decide a step-up permission itself — the door
+     * decides, not the route in front of it. Never recorded. Under `viaProxy`
+     * it is the actor's: the proxy's own fresh sign-in is what counts (#1762).
+     */
+    signIn?: import('./AuthManager.js').SignInRecord;
+    /**
+     * The highest level this account's allowed sign-in methods can reach, at
+     * least 1 (#1690). A role's required level never exceeds it: an account
+     * with no way to reach AAL2 holds its roles at AAL1. Set where the request
+     * subject is built, beside `signIn` — under `viaProxy`, the actor's
+     * account's cap, since it is the actor who signs in (#1762).
+     */
+    aalCap?: import('../providers/BaseAuthProvider.js').Aal;
+}
+/**
+ * The subject of work with no request behind it (#631, #1212).
+ *
+ * A job enqueued at 09:00 and run at 09:12 must authorise against 09:12's
+ * roles, so it carries who asked and __no roles__ — they resolve at decision
+ * time. Until #1212 that shape was "a `PermissionSubject` whose `roles` happen
+ * to be absent", which the type could not tell apart from a caller that
+ * forgot them. `resolveRolesNow` says it on purpose: the compiler now refuses
+ * a subject missing `roles`, and this is the one sanctioned way to ask for
+ * live resolution. `viaToken` / `viaShare` / `viaProxy` ride along exactly as on a request.
+ */
+export interface JobSubject {
+    username: string;
+    isAuthenticated: boolean;
+    /** Roles are resolved live at decision time, not carried. */
+    resolveRolesNow: true;
+    viaToken?: AgentTokenGrant;
+    viaShare?: ShareGrant;
+    viaProxy?: ProxyClaim;
+}
+/**
+ * User creation input data
+ */
+interface UserCreateInput {
+    username: string;
+    email: string;
+    displayName?: string;
+    password: string;
+    roles?: string[];
+    isExternal?: boolean;
+    isActive?: boolean;
+    acceptLanguage?: string;
+    /** Freeze password/email/displayName against self-service change (#1029). */
+    profileLocked?: boolean;
+    /** A test account (#1805): attribute only, grants nothing. Default false. */
+    isTest?: boolean;
+}
+/**
+ * User update input data
+ */
+interface UserUpdateInput {
+    email?: string;
+    displayName?: string;
+    password?: string;
+    roles?: string[];
+    isActive?: boolean;
+    isExternal?: boolean;
+    /** A test account (#1805); the change is recorded on user-edit. */
+    isTest?: boolean;
+    preferences?: Partial<UserPreferences>;
+    profilePage?: string;
+    [key: string]: unknown;
+}
+/**
+ * UserManager - Handles user authentication, authorization, and roles
+ *
+ * Similar to JSPWiki's UserManager with role-based permissions. This manager
+ * orchestrates user operations through a pluggable provider system, allowing
+ * different storage backends (file, database, LDAP, etc.) to be used.
+ *
+ * Key responsibilities:
+ * - User authentication (login/logout)
+ * - Password management with hashing
+ * - Role and permission management
+ * - Session management
+ * - User profile management
+ * - Provider abstraction for storage
+ *
+ * Follows JSPWiki's provider pattern where the actual storage implementation
+ * is abstracted behind a provider interface. This allows for different storage
+ * backends (file, database, LDAP, etc.) to be swapped via configuration.
+ *
+ * @class UserManager
+ * @extends BaseManager
+ *
+ * @property {UserProvider|null} provider - The active user storage provider
+ * @property {string} providerClass - The class name of the loaded provider
+ * @property {Map<string, Role>} roles - Role definitions
+ * @property {Map<string, string>} permissions - Permission definitions
+ * @property {string} passwordSalt - Salt for password hashing
+ * @property {number} sessionExpiration - Session expiration time in milliseconds
+ * @property {string} defaultTimezone - Default timezone for users
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link FileUserProvider} for default provider implementation
+ *
+ * @example
+ * const userManager = engine.getManager('UserManager');
+ * const ok = await authManager.authenticate('password', { username: 'admin', password: 'password' });
+ * if (user) logger.info('Logged in:', user.username);
+ */
+declare class UserManager extends BaseManager {
+    private provider;
+    private providerClass?;
+    private passwordSalt?;
+    /**
+     * Creates a new UserManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the UserManager and load the configured provider
+     *
+     * Loads the user provider, role definitions, and creates a default admin
+     * user if no users exist.
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available or provider fails to load
+     *
+     * @example
+     * await userManager.initialize();
+     * // Creates default admin if no users exist
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /** An email as accounts are compared on it (#1748): trimmed, any case. No provider rules (Gmail dots, plus addressing, aliases). */
+    private static emailKey;
+    /** The accounts holding this email, by username. Empty for no email. */
+    private accountsWithEmail;
+    /**
+     * One email, one account (#1748): refuse to save an email another account
+     * already has. Not a setting. Thrown as `email-taken`, so registration shows
+     * its safe message and other routes their own.
+     */
+    private assertEmailFree;
+    /**
+     * Accounts that share an email, saved before #1748 refused it. They are not
+     * changed — an admin decides — but they are never silent: the manager is
+     * degraded (dashboard, `manager-state-change` audit), the log says which,
+     * and admins get a notification. Until resolved, a lookup by that email
+     * refuses (see `getUserByEmail`).
+     */
+    private reportDuplicateEmails;
+    /**
+     * Normalize provider name from configuration (lowercase) to class name (PascalCase)
+     * @param {string} providerName - Provider name from configuration (e.g., 'fileuserprovider')
+     * @returns {string} Normalized class name (e.g., 'FileUserProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Get the current user provider instance
+     * @returns {UserProvider | null} The active provider
+     */
+    getCurrentUserProvider(): UserProvider | null;
+    /**
+     * Get provider information
+     * @private
+     */
+    private getProviderInfo;
+    /**
+     * Hash a password for storage (#1042).
+     *
+     * scrypt with a per-user random salt. Was one round of SHA-256 with a single
+     * instance-wide salt, which is fast to crack offline and made two users with
+     * the same password produce identical hashes.
+     *
+     * @param {string} password - Plain text password
+     * @returns {string} Self-describing hash: `scrypt$N$r$p$salt$hash`
+     */
+    hashPassword(password: string): Promise<string>;
+    /**
+     * Verify a password against a stored hash, in either scheme (#1042).
+     *
+     * Pre-#1042 hashes keep verifying against the instance-wide salt — the
+     * plaintext is not recoverable, so they cannot be converted in bulk. They are
+     * upgraded individually by `PasswordAuthProvider` on the next successful check (#1758).
+     *
+     * @param {string} password - Plain text password
+     * @param {string} hash - Stored hash, either scheme
+     * @returns {boolean} True if password matches
+     */
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    /** The value shipped in config; also the fallback when config is unreadable. */
+    private static readonly DEFAULT_BOOTSTRAP_PASSWORD;
+    /**
+     * Read the bootstrap password for the `admin` account.
+     *
+     * `ngdpbase.user.security.defaultpassword` ships as `admin123`, so a fresh
+     * install comes up unattended and the setup wizard is reachable. An operator
+     * who prefers it out of the repository can point the key at an env-ref —
+     * `"$NGDPBASE_ADMIN_PASSWORD"` — and a bare ref is strict, so an unset
+     * variable stops the boot rather than silently falling back to the default.
+     *
+     * The literal fallback below covers only a missing or blank config value,
+     * which is what an embedder or a partially-mocked test sees. It deliberately
+     * matches the shipped default: a caller with no configuration should get the
+     * documented account, not an exception.
+     */
+    private getBootstrapPassword;
+    /**
+     * Same, but null instead of throwing. For callers that merely want to WARN
+     * about the bootstrap password still being in force — an install with no
+     * such variable set is the normal case there, not an error.
+     */
+    private tryGetBootstrapPassword;
+    /**
+     * Check whether the admin account still has the configured bootstrap
+     * password. False when none is configured — there is then no shipped,
+     * well-known credential to warn about.
+     *
+     * @returns {Promise<boolean>} True if admin still has the bootstrap password
+     */
+    isAdminUsingDefaultPassword(): Promise<boolean>;
+    /**
+     * The roles an account is made with: those its sign-up path or the admin
+     * chose, plus `ngdpbase.user.account-roles`, the roles every account gets
+     * (#1539 — `vault-owner`, without which a person's own vaults refuse them).
+     */
+    private withAccountRoles;
+    /** `ngdpbase.user.account-roles`: the roles every account holds (#1539). */
+    private accountRoles;
+    /**
+     * Accounts made before a role joined `ngdpbase.user.account-roles` get it
+     * once, at boot (#1539) — RoleManager decides "once" and records each grant.
+     */
+    private grantAccountRolesToExistingAccounts;
+    /**
+     * Create the bootstrap admin account.
+     *
+     * Called only when the user store is empty. The password is
+     * `ngdpbase.user.security.defaultpassword`, which ships as `admin123` so a
+     * first run needs no setup; a headless install refuses that well-known value
+     * (#1087), and startup warns while the admin still uses it. Low first-run
+     * friction is a decision: warn, never force (crypto/auth review, 2026-10-05).
+     */
+    createDefaultAdmin(): Promise<void>;
+    /**
+     * The stored password hash of an active local account, or null (#1758).
+     * The password check is `PasswordAuthProvider`'s, through AuthManager — the
+     * one door for every check of a secret; this manager keeps the hash on the
+     * account and hands it only to that check. `getUser()` still strips it.
+     */
+    storedPasswordHash(username: string): Promise<string | null>;
+    /**
+     * Replace a stored hash with one at the current cost, after a successful
+     * check (#1042): the only moment it can be done, since the old digest can't
+     * be converted. Called by `PasswordAuthProvider` (#1758).
+     */
+    upgradePasswordHash(username: string, newHash: string, legacy: boolean): Promise<void>;
+    /** Count a completed sign-in on the account: last sign-in and sign-in count (#1758; AuthManager calls it for a sign-in, never a re-check). */
+    recordSignIn(username: string): Promise<void>;
+    /**
+     * Check if a display name conflicts with existing page names or other users
+     * @param {string} displayName - Display name to check
+     * @param {string | null} excludeUsername - Username to exclude from the check (for updates)
+     * @returns {Promise<boolean>} True if conflict exists
+     */
+    checkDisplayNamePageConflict(displayName: string, excludeUsername?: string | null): Promise<boolean>;
+    /**
+     * Create a user page for a new user.
+     *
+     * The page is written AS the new user (#1462): it is their page, and the
+     * door takes a new page's author from who is acting. Written as the admin
+     * who created the account — or as whoever ran self-registration — the
+     * profile would be authored by them, and `author-lock` would leave the
+     * account's own owner unable to edit it.
+     *
+     * @param {User} user - User object
+     * @param ctx - Who created the account, for the log line only
+     * @returns {Promise<boolean>} True if user page was created successfully
+     */
+    createUserPage(user: User, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Who holds which role is RoleManager's (#1431 step 12). An account write
+     * that changes roles asks it; it is registered before UserManager, so its
+     * absence is a broken engine, not a degraded one.
+     */
+    private roleManager;
+    /** The subject's attributes are the PIP's (#1431 step 13); an account write asks it about names. */
+    private policyInformationPoint;
+    private auditSink;
+    /**
+     * Every account write goes through here (#1751): it writes, then bumps the
+     * account-data version, so cached renders that show names or decide by
+     * roles re-render.
+     */
+    private writeAccounts;
+    /**
+     * Create new user
+     * @param {UserCreateInput} userData - User data
+     * @returns {Promise<Omit<User, 'password'>>} Created user (without password)
+     */
+    createUser(userData: UserCreateInput, ctx: ActorContext): Promise<Omit<User, 'password'>>;
+    /**
+     * Update user
+     */
+    /**
+     * A forgotten password, reset with the 12 recovery words (#1452).
+     *
+     * The words are the account owner's own escrow: they unwrap the key the
+     * password used to, so proving them is proving you are the person the key
+     * was made for. The password wrap is replaced first — the recovery wrap and
+     * the key are unchanged, so every encrypted store still opens — and then the
+     * sign-in password is set, through `updateUser`, so the two stay one
+     * password and the change is recorded like any other.
+     *
+     * `false`, changing nothing, for any reason it cannot be done: no such
+     * account, an inactive or external one, no keys, or words that do not open
+     * them. The caller cannot tell which, so the door cannot be used to learn
+     * which accounts exist.
+     */
+    resetPasswordWithRecoveryWords(username: string, words: string, newPassword: string, ctx: ActorContext): Promise<boolean>;
+    updateUser(username: string, updates: UserUpdateInput, ctx: ActorContext): Promise<User>;
+    /**
+     * Delete user
+     */
+    deleteUser(username: string, ctx: ActorContext): Promise<boolean>;
+    /** Hand the account to AuthManager's one deactivation step (#1765); a failure there is logged, never thrown. */
+    private closeAccess;
+    getUsers(): Promise<Omit<User, 'password'>[]>;
+    getUser(username: string): Promise<Omit<User, 'password'> | undefined>;
+    /**
+     * Whether the account signs in with a password of its own: a local account
+     * whose record carries a hash. Asked here because this is the one door that
+     * sees the hash — `getUser()` strips it, which is why AuthManager's
+     * last-way-in rule, asking through `getUser()`, saw no password on any
+     * account and refused to remove anyone's only passkey (#1524).
+     */
+    hasPassword(username: string): Promise<boolean>;
+    getUserByEmail(email: string): Promise<Omit<User, 'password'> | undefined>;
+    /**
+     * #658: resolve the recipient address for /contact submissions.
+     *
+     * 1. Trimmed `recipientOverride` (from `ngdpbase.application.contact.recipient`)
+     *    if non-empty — used verbatim, may be a list or alias.
+     * 2. Else: first user with the `admin` role whose email is non-empty AND
+     *    not the install-default sentinel `admin@localhost`. The sentinel
+     *    keeps the contact feature dormant on fresh installs that haven't
+     *    set a real admin email yet, instead of mailing into a black hole.
+     * 3. Else: `null` — caller must render "Contact form is not configured"
+     *    rather than attempting to send.
+     *
+     * The returned address is server-side only; never render it to clients.
+     */
+    getContactRecipient(recipientOverride: string): Promise<string | null>;
+    /**
+     * Search users by username, displayName, or email (case-insensitive substring).
+     * Optionally filter by role and active status.
+     */
+    searchUsers(query: string, options: {
+        role?: string;
+        limit?: number;
+        activeOnly?: boolean;
+    }, ctx: ActorContext): Promise<Omit<User, 'password'>[]>;
+    /**
+     * Persist a Person record paired with a newly-created User. The install's
+     * anchor org (when configured) is referenced via `memberOf`; without it
+     * the Person is written without an org link. Failures are logged, not
+     * thrown — auth must still succeed if Person storage is degraded.
+     */
+    private syncPersonOnCreate;
+    private syncPersonOnUpdate;
+    private syncPersonOnDelete;
+    createSession(username: string, additionalData?: Record<string, unknown>): Promise<string>;
+    getSession(sessionId: string): Promise<UserSession | null>;
+    deleteSession(sessionId: string): Promise<void>;
+    deleteUserSessions(username: string): Promise<void>;
+    backup(): Promise<BackupData>;
+    restore(backupData: BackupData): Promise<void>;
+}
+export default UserManager;