@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/providers/BaseAuthProvider.d.ts

@@ -0,0 +1,220 @@
+/**
+ * BaseAuthProvider — pluggable authentication provider interface.
+ *
+ * All authentication methods (password, magic link, OAuth, etc.) implement
+ * this interface and are registered with AuthManager, which dispatches
+ * initiate/verify calls to the appropriate provider.
+ *
+ * Pattern mirrors BasePageProvider / BaseAttachmentProvider / BaseMediaProvider.
+ *
+ * @see AuthManager
+ * @see PasswordAuthProvider
+ * @see MagicLinkAuthProvider
+ */
+/**
+ * Context passed to initiate() for challenge-based auth flows.
+ *
+ * Note: providers that emit absolute URLs (magic-link verify links,
+ * OAuth callbacks) read the canonical base URL from ConfigurationManager
+ * at runtime — callers don't pass it in (#642 Iteration 3).
+ */
+export interface AuthInitiateContext {
+    /** Email address (magic link) */
+    email?: string;
+    /** URL to redirect to after successful authentication */
+    redirect?: string;
+    /**
+     * #1022: opaque per-request value identifying the browser that asked for the
+     * link, mirrored into an HTTP-only cookie. Stored with the token so the
+     * redeeming browser can be compared against the requesting one.
+     */
+    deviceState?: string;
+    /**
+     * #1743: the signed-in account an outside identity is being connected to.
+     * Absent for a sign-in. A flow started to connect never signs anyone in,
+     * and a sign-in flow never connects.
+     */
+    connectFor?: string;
+}
+/**
+ * Credentials passed to verify(). Fields used depend on the provider.
+ */
+export interface AuthVerifyCredentials {
+    /** Username — used by PasswordAuthProvider */
+    username?: string;
+    /** Password — used by PasswordAuthProvider */
+    password?: string;
+    /** One-time token — used by MagicLinkAuthProvider */
+    token?: string;
+    /** OAuth `state` from the callback — used by OidcAuthProvider */
+    state?: string;
+    /** The browser-binding value from the caller's cookie (#1022 magic link, #1630 OAuth) */
+    deviceState?: string;
+    /** A WebAuthn assertion and the single-use challenge it must answer — used by PasskeyAuthProvider (#448). */
+    webauthn?: {
+        response: unknown;
+        expectedChallenge: string;
+    };
+}
+/**
+ * Identity and authority of a delegated agent token (#946).
+ *
+ * Roles are deliberately absent: they are resolved live from the user record,
+ * so a token never carries a snapshot of authority that could outlive a change
+ * to the account.
+ */
+export interface ViaToken {
+    /** Token record id */
+    id: string;
+    /** Human-readable token name, used in logs and page provenance */
+    name: string;
+    /** Scope ceiling this token may act within */
+    scopes: string[];
+}
+/**
+ * Returned by verify() on success.
+ */
+export interface AuthResult {
+    /** Username of the authenticated user */
+    username: string;
+    /**
+     * Set by token-based providers (#946, #1048). Lets the caller enforce the
+     * token's scope ceiling and stamp page provenance.
+     *
+     * Declared here rather than read through a cast in AuthManager: the manager
+     * always passed this field along, but `AuthResult` did not admit it existed,
+     * so a provider that misspelled it or typed `scopes` wrongly still compiled
+     * and silently delivered nothing.
+     */
+    viaToken?: ViaToken;
+    /**
+     * The assurance level a bearer credential's sign-in reached (#1576), when
+     * it says. Roles above it step down for the request, as in a web session.
+     * Absent on credentials that carry no sign-in (agent tokens).
+     */
+    aal?: Aal;
+    /**
+     * What an outside identity provider said about its own sign-in (#1633), set
+     * only by outside sign-in providers. AuthManager reads it and decides what
+     * it counts for; a provider never does.
+     */
+    reported?: ReportedAssurance;
+}
+/**
+ * An outside identity provider's `amr` and `acr` (#1633), exactly as its
+ * verified ID token carried them: unchecked, so any type. AuthManager keeps
+ * only well-formed values (`reportedValues`) and maps them to a level
+ * (`outsideLevel`), counting them only for a provider the admin trusts.
+ */
+export interface ReportedAssurance {
+    amr?: unknown;
+    acr?: unknown;
+}
+/**
+ * NIST SP 800-63B authenticator assurance level a factor gives on its own (#1523).
+ * 0 is "not a factor" — a known device skips a prompt but proves nothing.
+ */
+export type Aal = 0 | 1 | 2 | 3;
+/** Phishing resistance, strongest last: `phr`, then `phrh` (hardware) (#1523). */
+export type PhishingResistance = 'phr' | 'phrh';
+/**
+ * What a provider gives as a sign-in factor, declared in its code (#1523).
+ *
+ * Configuration (`ngdpbase.auth.factors`) may lower these, never raise them:
+ * the code is the ceiling because the code is what actually checks the
+ * credential. Know / have / are and device-boundness are derived from `amr`,
+ * so there is one source for them.
+ */
+export interface FactorDescription {
+    /** RFC 8176 `amr` values, plus the unregistered `email` and `push`. */
+    amr: string[];
+    aal: Aal;
+    acr?: PhishingResistance;
+    /** Can start a sign-in, rather than only follow one as an additional factor. */
+    primary: boolean;
+}
+/**
+ * Interface all authentication providers must implement.
+ */
+export interface AuthProvider {
+    /** Unique identifier, e.g. 'password', 'magic-link', 'oauth-google' */
+    readonly id: string;
+    /** Human-readable name shown in admin UIs */
+    readonly displayName: string;
+    /**
+     * What this provider gives as a sign-in factor (#1523). Absent on providers
+     * that carry delegated credentials (agent tokens, bearer JWTs): a delegated
+     * credential is a scope ceiling, never a factor, and is never offered at
+     * sign-in.
+     */
+    readonly factor?: FactorDescription;
+    /** Whether the bearer middleware tries this provider for `Authorization: Bearer` (#946, #1576). */
+    readonly acceptsBearer?: boolean;
+    /**
+     * Initiate a challenge-based auth flow.
+     * Called for flows that require a side-effect before verification
+     * (e.g. send a magic-link email, start an OAuth redirect).
+     * Credential-based providers (password) do not need to implement this.
+     */
+    initiate?(context: AuthInitiateContext): Promise<void>;
+    /**
+     * Verify credentials or a token.
+     * @returns AuthResult on success, null on failure.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    /**
+     * Consume a single-use token after a session has been created.
+     * Only needed for token-based providers (magic link, OAuth).
+     */
+    /**
+     * Consume a single-use token, returning whether this caller consumed it.
+     *
+     * #1021: callers gate session creation on the return value — a `false` means
+     * another request got there first and this one must not establish a session.
+     * An implementation that cannot distinguish the two must return `false`
+     * rather than `true`, since a wrong `true` re-opens the double-session hole.
+     */
+    consumeToken?(token: string): boolean;
+    /**
+     * Begin a redirect-based flow; returns the URL to send the browser to (#1049).
+     *
+     * Distinct from `initiate()`, which performs a side effect and returns
+     * nothing (magic-link sends an email). Here the URL *is* the result.
+     *
+     * Throws rather than returning a fallback when the flow cannot be started:
+     * there is no sensible substitute for "where should the browser go", and an
+     * empty string would send it nowhere with no error to explain why.
+     *
+     * May answer asynchronously: an OpenID Connect provider reads its issuer's
+     * discovery document before it knows where to send the browser (#1743).
+     */
+    startFlow?(context: AuthInitiateContext): string | Promise<string>;
+    /**
+     * Where the user was headed before this flow began, keyed by the flow's own
+     * handle — a magic-link token, an OAuth state nonce (#1049).
+     *
+     * Must be read BEFORE `consumeToken()`, which deletes the entry.
+     *
+     * Returns `'/'` rather than throwing when the handle is unknown: losing the
+     * destination degrades the landing page, it does not invalidate the sign-in,
+     * and failing the login over it would be a worse outcome than the front page.
+     */
+    getFlowRedirect?(handle: string): string;
+    /**
+     * The device-state value recorded when this flow was initiated (#1022), or
+     * null when the provider does not bind, or the handle predates the feature.
+     *
+     * Must be read BEFORE `consumeToken()`, which deletes the entry.
+     */
+    getDeviceState?(handle: string): string | null;
+    /**
+     * Create the account behind a first-time credential (#1049).
+     *
+     * Called before `verify()` on flows that provision on first sign-in, because
+     * the account must exist before a session can name it.
+     *
+     * @returns true if an account was created or already existed; false if the
+     *   handle is unusable — which the caller should treat as a failed sign-in.
+     */
+    provisionIfNew?(handle: string): Promise<boolean>;
+}

package/lib/src/providers/BaseCacheProvider.d.ts

@@ -0,0 +1,140 @@
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { ProviderInfo } from '../types/Provider.js';
+import BaseProvider from './BaseProvider.js';
+/**
+ * Cache statistics structure
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of keys in cache */
+    keys: number;
+    /** Approximate memory usage of keys */
+    ksize: number;
+    /** Approximate memory usage of values */
+    vsize: number;
+    /** Number of set operations */
+    sets: number;
+    /** Number of delete operations */
+    deletes: number;
+    /** Cache hit rate percentage */
+    hitRate: number;
+}
+/**
+ * Backup data structure
+ */
+export interface BackupData {
+    provider: string;
+    initialized: boolean;
+    timestamp: string;
+    [key: string]: unknown;
+}
+/**
+ * BaseCacheProvider - Base class for all cache providers
+ *
+ * Provides the interface that all cache providers must implement.
+ * Follows the provider pattern established in AttachmentManager and PageManager.
+ *
+ * Cache providers implement different storage backends (node-cache, Redis, etc.)
+ *
+ * @class BaseCacheProvider
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Whether provider has been initialized
+ *
+ * @see {@link NodeCacheProvider} for in-memory implementation
+ * @see {@link RedisCacheProvider} for Redis implementation
+ * @see {@link CacheManager} for usage
+ */
+declare abstract class BaseCacheProvider extends BaseProvider {
+    /**
+     * Reference to the wiki engine instance
+     */
+    protected engine: WikiEngine;
+    /**
+     * Whether the provider has been initialized
+     */
+    protected initialized: boolean;
+    /**
+     * Creates a new cache provider
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the cache provider
+     * Implementations should load configuration from ConfigurationManager
+     * @returns {Promise<void>}
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Get provider information
+     * @returns {ProviderInfo} Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Get a value from the cache
+     * @template T
+     * @param {string} key - The cache key
+     * @returns {Promise<T | undefined>} The cached value or undefined if not found
+     */
+    abstract get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache
+     * @template T
+     * @param {string} key - The cache key
+     * @param {T} value - The value to cache
+     * @param {number} [ttlSec] - Time to live in seconds
+     * @returns {Promise<void>}
+     */
+    abstract set<T = unknown>(key: string, value: T, ttlSec?: number): 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>}
+     */
+    abstract del(keys: string | string[]): Promise<void>;
+    /**
+     * Clear cache entries
+     * @param {string} [pattern] - Optional pattern to match keys (e.g., 'user:*')
+     * @returns {Promise<void>}
+     */
+    abstract clear(pattern?: string): Promise<void>;
+    /**
+     * Get keys matching a pattern
+     * @param {string} [pattern='*'] - Pattern to match (e.g., 'user:*' or '*' for all)
+     * @returns {Promise<string[]>} Array of matching keys
+     */
+    abstract keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     * @returns {Promise<CacheStats>} Cache statistics
+     */
+    abstract stats(): Promise<CacheStats>;
+    /**
+     * Check if the cache provider is healthy/connected
+     * @returns {Promise<boolean>} True if healthy
+     */
+    abstract isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the cache provider
+     * @returns {Promise<void>}
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Backup cache configuration and state (optional)
+     * @returns {Promise<BackupData>} Backup data
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore cache from backup (optional)
+     * @param {BackupData} _backupData - Backup data
+     * @returns {Promise<void>}
+     */
+    restore(_backupData: BackupData): Promise<void>;
+}
+export default BaseCacheProvider;

package/lib/src/providers/BaseCredentialsProvider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The credentials store (#1524): an account's ways in beyond its password.
+ *
+ * Passwords stay on the user record and are never copied here (decided
+ * 2026-10-02). This store holds passkeys, verified email / phone addresses
+ * and known devices (TOTP seeds once #421 is built) — one row each, many per
+ * account.
+ *
+ * Every row is signed with `NGDPBASE_CREDENTIALS_KEY` (the instance `.env`).
+ * A row that does not verify is never returned: a planted row is ignored, and
+ * reported through `onRejected` so the owner of the store raises the alert.
+ *
+ * AuthManager is the only door; nothing else reads or writes a provider.
+ */
+import BaseProvider from './BaseProvider.js';
+/** The environment variable holding the signing and encryption key. */
+export declare const CREDENTIALS_KEY_ENV = "NGDPBASE_CREDENTIALS_KEY";
+/**
+ * `identity` (#1743): an outside OpenID Connect identity connected to the
+ * account — subject `${iss}#${sub}`, label the provider's name, secret the
+ * provider's verified email ('' when none).
+ *
+ * `proxy` (#1762): a proxy grant — the row's `username` is the person
+ * represented, `subject` the grant id, `secret` the grant's terms as JSON
+ * (whom it is for, the permissions, who made it, when it ends). Never a way
+ * in; AuthManager reads and writes it only through its proxy-grant methods.
+ */
+export type CredentialKind = 'passkey' | 'totp' | 'email' | 'sms' | 'device' | 'identity' | 'proxy';
+export declare const CREDENTIAL_KINDS: readonly CredentialKind[];
+/** One credential, as stored. */
+export interface CredentialRecord {
+    id: string;
+    username: string;
+    kind: CredentialKind;
+    /** What identifies it within its kind: a passkey's credential id, an address, a device token's hash, an outside identity's `iss#sub`. */
+    subject: string;
+    /** Kind-specific: a public key and counter, or empty (an encrypted TOTP seed once #421 is built). */
+    secret: string;
+    /** What the person calls it — "Jim's iPhone". */
+    label: string;
+    /** RFC 3339 with offset. */
+    createdAt: string;
+    lastUsedAt?: string;
+}
+/** Why a stored row was refused. */
+export interface RejectedCredential {
+    /** What could be read of it — never trusted, only reported. */
+    row: Partial<CredentialRecord>;
+    reason: 'bad-signature' | 'unsigned' | 'malformed';
+}
+declare abstract class BaseCredentialsProvider extends BaseProvider {
+    /**
+     * Load the store. Rows that fail verification sign no one in and are
+     * reported; they are kept, unchanged, in quarantine (#1633) so a lost or
+     * changed key does not destroy them on the next write.
+     */
+    abstract initialize(onRejected: (rejected: RejectedCredential[]) => void): Promise<void>;
+    /** Rows held in quarantine because they failed verification (#1633). */
+    abstract quarantined(): RejectedCredential[];
+    /**
+     * Re-sign every quarantined row that is well formed under the current key
+     * and trust it again (#1633). Malformed rows, and rows that would duplicate a
+     * trusted credential, stay quarantined. Returns the rows now trusted.
+     */
+    abstract retrustQuarantined(): Promise<CredentialRecord[]>;
+    /** A person's verified credentials, oldest first. */
+    abstract list(username: string): CredentialRecord[];
+    abstract get(id: string): CredentialRecord | null;
+    /** Every verified row of one kind, whoever's, oldest first (#1762: the grants naming a person as proxy). */
+    abstract listKind(kind: CredentialKind): CredentialRecord[];
+    /** Add a row; refuses a second row with the same kind and subject. */
+    abstract add(record: CredentialRecord): Promise<void>;
+    /** Remove a row; returns whether it existed. */
+    abstract remove(id: string): Promise<boolean>;
+    /** The row with this kind and subject, which are unique together; null when none. */
+    abstract findBySubject(kind: CredentialKind, subject: string): CredentialRecord | null;
+    /** Record that a credential was just used, and its new secret when that changes (a passkey's counter). */
+    abstract touch(id: string, at: string, secret?: string): Promise<void>;
+    /** Change a row's display name; the row is re-signed. False when there is no such row. */
+    abstract relabel(id: string, label: string): Promise<boolean>;
+    /** Where it is kept, for the admin view. */
+    abstract location(): string;
+}
+export default BaseCredentialsProvider;

package/lib/src/providers/BaseDatabaseProvider.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The application database (#1536): the one connection the row-storing
+ * providers share. A database provider opens it under its key, runs the
+ * migration ledger, answers for its integrity and closes it.
+ * `DatabaseManager` is the only door to it — nothing else opens a handle.
+ *
+ * Ported from yourPHR (yourphr#617), where it is in production.
+ */
+import BaseProvider from './BaseProvider.js';
+declare abstract class BaseDatabaseProvider<Handle = unknown> extends BaseProvider {
+    /** The open, migrated connection, for the providers built over it. */
+    abstract get handle(): Handle;
+    abstract integrityOk(): boolean;
+    /** Where the data lives and how big it is. */
+    abstract storage(): {
+        location: string;
+        sizeBytes: number;
+        encrypted: boolean;
+    };
+    abstract close(): void;
+}
+export default BaseDatabaseProvider;

package/lib/src/providers/BaseDatabaseProvider.js

@@ -0,0 +1,12 @@
+/**
+ * The application database (#1536): the one connection the row-storing
+ * providers share. A database provider opens it under its key, runs the
+ * migration ledger, answers for its integrity and closes it.
+ * `DatabaseManager` is the only door to it — nothing else opens a handle.
+ *
+ * Ported from yourPHR (yourphr#617), where it is in production.
+ */
+import BaseProvider from './BaseProvider.js';
+class BaseDatabaseProvider extends BaseProvider {
+}
+export default BaseDatabaseProvider;

package/lib/src/providers/BaseLoggingProvider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BaseLoggingProvider - Base class for all logging providers (Issue #169)
+ *
+ * Encapsulates winston transport + format construction behind the provider
+ * pattern, consistent with the Base*Provider family
+ * (Search/Audit/Cache/Page/User/...).
+ *
+ * IMPORTANT — deliberate deviation from the engine-based provider pattern:
+ * the logger is bootstrapped at module load (`src/utils/logger.ts`), long
+ * before the WikiEngine or ConfigurationManager exist, and is imported by
+ * virtually every module (including ConfigurationManager itself). A logging
+ * provider therefore CANNOT take an engine or read ConfigurationManager in a
+ * constructor/initialize() — doing so would create a bootstrap cycle. It is a
+ * pure, dependency-free transport/format factory. Provider *selection* happens
+ * later in `WikiEngine.initialize()` once config is resolved.
+ *
+ * @class BaseLoggingProvider
+ * @abstract
+ *
+ * @see {@link FileLoggingProvider} for the default file+console implementation
+ * @see {@link module:logger} for usage / selection
+ */
+import type Transport from 'winston-transport';
+import type { Logform } from 'winston';
+import BaseProvider from './BaseProvider.js';
+/**
+ * Logger configuration passed to a provider when (re)building transports.
+ * Mirrors {@link module:logger.LoggerConfig}.
+ */
+export interface LoggingProviderConfig {
+    /** Log level (error, warn, info, debug) */
+    level?: string;
+    /** Log directory path — file transport is only added when this is set */
+    dir?: string;
+    /** Max log file size in bytes or string form (e.g. '1MB') */
+    maxSize?: number | string;
+    /** Max number of rotated log files */
+    maxFiles?: number;
+}
+/** Provider metadata, consistent with the other Base*Provider classes */
+export interface LoggingProviderInfo {
+    name: string;
+    version: string;
+    description: string;
+    features: string[];
+}
+declare abstract class BaseLoggingProvider extends BaseProvider {
+    /**
+     * Build the winston transports for the given configuration.
+     *
+     * @param config - Resolved logger configuration
+     * @returns Array of winston transport instances
+     * @abstract
+     */
+    abstract createTransports(config: LoggingProviderConfig): Transport[];
+    /**
+     * Build the winston log format. Default is a timestamped single-line
+     * `printf`. Subclasses may override for structured/JSON output.
+     *
+     * @returns winston format
+     */
+    abstract createFormat(): Logform.Format;
+    /**
+     * Provider metadata.
+     */
+    getProviderInfo(): LoggingProviderInfo;
+}
+export default BaseLoggingProvider;

package/lib/src/providers/BaseLoggingProvider.js

@@ -0,0 +1,37 @@
+/**
+ * BaseLoggingProvider - Base class for all logging providers (Issue #169)
+ *
+ * Encapsulates winston transport + format construction behind the provider
+ * pattern, consistent with the Base*Provider family
+ * (Search/Audit/Cache/Page/User/...).
+ *
+ * IMPORTANT — deliberate deviation from the engine-based provider pattern:
+ * the logger is bootstrapped at module load (`src/utils/logger.ts`), long
+ * before the WikiEngine or ConfigurationManager exist, and is imported by
+ * virtually every module (including ConfigurationManager itself). A logging
+ * provider therefore CANNOT take an engine or read ConfigurationManager in a
+ * constructor/initialize() — doing so would create a bootstrap cycle. It is a
+ * pure, dependency-free transport/format factory. Provider *selection* happens
+ * later in `WikiEngine.initialize()` once config is resolved.
+ *
+ * @class BaseLoggingProvider
+ * @abstract
+ *
+ * @see {@link FileLoggingProvider} for the default file+console implementation
+ * @see {@link module:logger} for usage / selection
+ */
+import BaseProvider from './BaseProvider.js';
+class BaseLoggingProvider extends BaseProvider {
+    /**
+     * Provider metadata.
+     */
+    getProviderInfo() {
+        return {
+            name: 'BaseLoggingProvider',
+            version: '1.0.0',
+            description: 'Base logging provider interface',
+            features: []
+        };
+    }
+}
+export default BaseLoggingProvider;