@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,125 @@
+/**
+ * MagicLinkAuthProvider — passwordless authentication via one-time email links.
+ *
+ * Registered by AuthManager when `ngdpbase.auth.magic-link.enabled` is true.
+ *
+ * Flow:
+ *   1. initiate()  — look up user by email, generate token, send link via mail transport
+ *   2. verify()    — validate token (exists + not expired), return AuthResult
+ *   3. consumeToken() — delete token; its return value gates the session (#1021)
+ *
+ * `verify()` being side-effect free is load-bearing, not incidental (#1019): the
+ * route layer calls it twice, once on the GET that renders the sign-in
+ * confirmation page and again on the POST that completes the login. Only the
+ * POST consumes. Moving consumption into verify() would reintroduce the bug
+ * where a mail scanner's link pre-fetch burns the token before the user clicks.
+ *
+ * Tokens are in-memory only — lost on restart, acceptable for the default 15-min TTL.
+ *
+ * @see AuthManager
+ * @see BaseAuthProvider
+ */
+import type { AuthProvider, AuthInitiateContext, AuthVerifyCredentials, AuthResult, FactorDescription } from './BaseAuthProvider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { MailProvider } from '../mail/MailProvider.js';
+/**
+ * What an email link gives, in either role — starting a sign-in or confirming
+ * one as a second factor (#1523: one email-link factor). Email is never
+ * phishing-resistant and never above AAL1 (SP 800-63B §5.1.3.1).
+ */
+export declare const EMAIL_FACTOR: {
+    amr: string[];
+    aal: 1;
+};
+export interface MagicLinkConfig {
+    ttlMs: number;
+    mailProvider: MailProvider;
+}
+export declare class MagicLinkAuthProvider implements AuthProvider {
+    private engine;
+    private config;
+    readonly id = "magic-link";
+    readonly displayName = "Magic Link";
+    /** Email is never phishing-resistant and never above AAL1: SP 800-63B §5.1.3.1 bars it as out-of-band (#1523). */
+    readonly factor: FactorDescription;
+    /** token → entry */
+    private tokens;
+    /** email → timestamp of last request (rate-limit) */
+    private rateLimitMap;
+    constructor(engine: WikiEngine, config: MagicLinkConfig);
+    /**
+     * Initiate the magic-link flow: look up the user, generate a token, send the email.
+     * Silently succeeds if the email is not registered — prevents user enumeration.
+     */
+    initiate(context: AuthInitiateContext): Promise<void>;
+    /**
+     * Verify a token. Returns AuthResult on success, null if invalid or expired.
+     * Does NOT consume the token — call consumeToken() after the session is created.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    /**
+     * Delete the token and report whether THIS caller was the one that did.
+     *
+     * #1021: the return value is the single-use gate, not a courtesy. The route
+     * used to verify, then consume, with an `await` between the two — so two
+     * POSTs carrying the same token (a double-clicked confirmation button, a
+     * client retry, a prefetch racing the real submit) could both clear
+     * verification before either consumed, and both would then establish a
+     * session. #1019's CSRF-protected POST does not close that: both submits
+     * come from the same session with the same valid token.
+     *
+     * `Map.delete` returns true only for the call that found an entry, and it is
+     * synchronous so it cannot interleave. Exactly one caller can ever see true,
+     * which makes consumption — not verification — the thing a session is gated
+     * on.
+     */
+    consumeToken(token: string): boolean;
+    /**
+     * The requesting browser's state value for this token (#1022), or null.
+     *
+     * Must be read BEFORE consumeToken(), which deletes the entry — same
+     * constraint as getFlowRedirect below, and for the same reason.
+     */
+    getDeviceState(token: string): string | null;
+    /**
+     * Where the user was headed before the link was issued (#1049).
+     *
+     * Named for the capability rather than the mechanism: GoogleOIDCProvider
+     * answers the same question keyed by a state nonce, and the two used to be
+     * `getTokenRedirect` / `getStateRedirect`, which is why AuthManager needed a
+     * method per provider to ask it.
+     *
+     * Must be read BEFORE consumeToken(), which deletes the entry.
+     */
+    getFlowRedirect(token: string): string;
+    /**
+     * Create the account behind a new-user token (#1026).
+     *
+     * Called from the POST that completes sign-in, never from the GET — so a mail
+     * scanner pre-fetching the link cannot bring an account into existence, for
+     * the same reason it cannot consume the token (#1019).
+     *
+     * The account is created with `isExternal: true`, which stores an empty
+     * password hash. `UserManager.verifyPassword` refuses an empty stored hash
+     * outright (#1042), so these accounts cannot be logged into with a password
+     * by any input — magic link is structurally their only way in.
+     *
+     * Idempotent: a token whose account already exists is a no-op, so a double
+     * submit cannot fail the second time.
+     *
+     * @returns true if the token is usable (existing user, or newly created)
+     */
+    provisionIfNew(token: string): Promise<boolean>;
+    /** Whether an unknown email may create an account by verifying a link (#1026). */
+    private isAutoProvisionEnabled;
+    /**
+     * Role for auto-provisioned users. An unknown role name falls back to
+     * `reader` with a warning — a typo should degrade to read-only, not throw
+     * mid-signup or silently mint a more privileged account than intended.
+     */
+    private resolveDefaultRole;
+    private isRateLimited;
+    private cleanupExpired;
+    /** Exposed for testing */
+    getTokenCount(): number;
+}

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

@@ -0,0 +1,72 @@
+import BaseCacheProvider, { CacheStats } from './BaseCacheProvider.js';
+import type { ProviderInfo } from '../types/Provider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * NullCacheProvider - No-op cache provider
+ *
+ * Used when caching is disabled or for testing.
+ * All cache operations are no-ops that return immediately.
+ */
+declare class NullCacheProvider extends BaseCacheProvider {
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the null cache provider (no-op)
+     * @returns {Promise<void>}
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get provider information
+     * @returns {ProviderInfo} Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Get a value from the cache (always returns undefined)
+     * @template T
+     * @param {string} _key - The cache key
+     * @returns {Promise<T | undefined>} Always undefined
+     */
+    get<T = unknown>(_key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache (no-op)
+     * @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>}
+     */
+    set<T = unknown>(_key: string, _value: T, _ttlSec?: number): Promise<void>;
+    /**
+     * Delete one or more keys from the cache (no-op)
+     * @param {string | string[]} _keys - Single key or array of keys to delete
+     * @returns {Promise<void>}
+     */
+    del(_keys: string | string[]): Promise<void>;
+    /**
+     * Clear cache entries (no-op)
+     * @param {string} [_pattern] - Optional pattern to match keys
+     * @returns {Promise<void>}
+     */
+    clear(_pattern?: string): Promise<void>;
+    /**
+     * Get keys matching a pattern (always returns empty array)
+     * @param {string} [_pattern='*'] - Pattern to match
+     * @returns {Promise<string[]>} Empty array
+     */
+    keys(_pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics (all zeros)
+     * @returns {Promise<CacheStats>} Cache statistics with all zeros
+     */
+    stats(): Promise<CacheStats>;
+    /**
+     * Check if the cache provider is healthy (always true)
+     * @returns {Promise<boolean>} Always true
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the cache provider (no-op)
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+}
+export default NullCacheProvider;

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

@@ -0,0 +1,180 @@
+/**
+ * OidcAuthProvider — signing in through an outside OpenID Connect provider (#1743).
+ *
+ * One class, one registered instance per configured issuer (`oidc:<name>`),
+ * registered by AuthManager from `ngdpbase.auth.oidc.providers` (and the old
+ * `ngdpbase.auth.google-oidc.*` keys, read as the `google` entry). Routes never
+ * call it: AuthManager is the one door.
+ *
+ * What an outside sign-in may do (decided 2026-10-10, docs/planning/authentication.md):
+ * - The identity is the issuer plus the subject (`iss` + `sub`, OIDC Core §5.7),
+ *   stored as a credentials-store row of kind `identity`. Only an identity
+ *   already connected to an account signs anyone in. Email never matches or
+ *   signs anyone in here.
+ * - It gives no roles: a provider's groups and roles claims are never read.
+ * - No access or refresh token is kept; nothing needs them.
+ *
+ * Each flow is protected as `GoogleOIDCProvider` was (#1630): a single-use
+ * `state` bound to the starting browser by an HTTP-only cookie, PKCE (S256),
+ * an OIDC `nonce`, and the ID token's signature, issuer, audience and expiry.
+ *
+ * Apple (slice 4b) differs in two ways handled here: its client secret is a
+ * JWT signed per exchange (`SignedClientSecret`), and it POSTs the callback
+ * (`responseMode: 'form_post'`), which `middleware/outsideCallbackRelay.ts`
+ * turns into the usual GET before the session and CSRF see it.
+ *
+ * Discovery (`/.well-known/openid-configuration`) and the issuer's keys are
+ * fetched through `guardedFetch`, like every outbound request (#1133), and
+ * cached. Flow state is in memory: a restart drops a sign-in in progress.
+ *
+ * @see AuthManager
+ * @see BaseAuthProvider
+ */
+import * as crypto from 'crypto';
+import type { EgressPolicy } from '../http/ssrf.js';
+import type { AuthInitiateContext, AuthProvider, AuthResult, AuthVerifyCredentials, FactorDescription, ReportedAssurance } from './BaseAuthProvider.js';
+/**
+ * A provider button's icon (#1781): an image (an `https://` address or a site
+ * path), a Font Awesome class, or a logo the button partial draws itself.
+ */
+export type OutsideProviderIcon = {
+    kind: 'image';
+    src: string;
+} | {
+    kind: 'fa';
+    className: string;
+} | {
+    kind: 'builtin';
+    id: 'google';
+};
+/** One configured provider, as AuthManager resolved it from configuration. */
+export interface OidcProviderConfig {
+    /** The entry's name; the provider's id is `oidc:<name>`, its URLs `/auth/oauth/<name>`. */
+    name: string;
+    displayName: string;
+    /** What its sign-in and Connect buttons show beside `displayName` (#1781). */
+    icon: OutsideProviderIcon;
+    /** The issuer identifier, exactly as the issuer's discovery document states it. */
+    issuer: string;
+    clientId: string;
+    /**
+     * How the site proves itself at the token endpoint: a shared secret,
+     * already resolved from its environment reference, or (Apple) a key it signs
+     * a short-lived client secret with. Never logged.
+     */
+    clientSecret: string | SignedClientSecret;
+    /** This site's callback, registered with the provider. */
+    redirectUri: string;
+    /** Where outbound requests may go (ngdpbase.security.egress.*). */
+    policy: EgressPolicy;
+    /**
+     * `form_post`: the issuer POSTs the code and state back (Apple, whenever
+     * scopes are asked for). AuthManager answers `callbackIsPosted` from it, and
+     * the relay in `middleware/outsideCallbackRelay.ts` turns the POST into the
+     * usual GET callback.
+     */
+    responseMode?: 'form_post';
+    /** The issuer may send `email_verified` as the string `"true"` / `"false"` (Apple); only true counts either way. */
+    emailVerifiedMayBeString?: boolean;
+}
+/**
+ * Apple's client secret is not a shared secret but a JWT the site signs
+ * (ES256) with a key from its Apple developer account: `kid` the key's id,
+ * `iss` the team id, `sub` the client id, `aud` the issuer, and an expiry
+ * of at most six months. Signed afresh for each code exchange, valid 5 minutes.
+ */
+export interface SignedClientSecret {
+    teamId: string;
+    keyId: string;
+    /** The EC P-256 private key (Apple's `.p8`), checked by AuthManager when it registers the provider. */
+    privateKey: crypto.KeyObject;
+}
+/** An outside identity, as the provider vouched for it. */
+export interface OidcIdentity {
+    /** `${iss}#${sub}`, with the configured issuer — the credentials-store subject. */
+    subject: string;
+    /** The provider's email, only when it reports it verified; '' otherwise. */
+    email: string;
+    /** The ID token's `amr` and `acr`, as sent (#1633); AuthManager decides what they count for. */
+    reported: ReportedAssurance;
+}
+/** How the provider reaches connected identities: the credentials store, through AuthManager. */
+export interface IdentityStore {
+    /** The row connecting this subject to an account, or null. */
+    find(subject: string): {
+        id: string;
+        username: string;
+    } | null;
+    /** Record a sign-in with it, and the provider's current verified email. */
+    used(id: string, at: string, email: string): Promise<void>;
+}
+export declare class OidcAuthProvider implements AuthProvider {
+    private readonly config;
+    private readonly identities;
+    readonly id: string;
+    readonly displayName: string;
+    readonly icon: OutsideProviderIcon;
+    /**
+     * AAL1 with no `amr`: what is offered, and what a sign-in counts for unless
+     * the admin trusts this provider's own second factor (`trust-mfa`, #1633),
+     * when AuthManager maps the reported `amr` / `acr` instead
+     * (`outsideLevel`). Primary: it starts a sign-in on its own.
+     */
+    readonly factor: FactorDescription;
+    private readonly flows;
+    private discovery;
+    private keys;
+    constructor(config: OidcProviderConfig, identities: IdentityStore);
+    /** The configured issuer; an identity row's subject starts with it and `#`. */
+    get issuer(): string;
+    /** The entry's name, as in its URLs. */
+    get name(): string;
+    /** Whether the issuer POSTs the callback (`response_mode=form_post`) instead of redirecting to it. */
+    get callbackIsPosted(): boolean;
+    /**
+     * Begin a sign-in, or a connection when `connectFor` names the signed-in
+     * account: keep the flow's state and return the provider's authorization URL.
+     */
+    startFlow({ redirect, deviceState, connectFor }?: AuthInitiateContext): Promise<string>;
+    /** Where the person was headed when the flow began; read before `consumeToken`. */
+    getFlowRedirect(state: string): string;
+    /** The account this flow is connecting an identity to, or null for a sign-in or an unknown flow. */
+    getFlowConnectFor(state: string): string | null;
+    /**
+     * Finish a sign-in: the account whose connected identity this is, or null.
+     * A flow started to connect never signs in. An identity connected to no
+     * account is refused, and kept on the flow until it is consumed, so
+     * AuthManager can decide what happens next (`unconnectedIdentity`);
+     * nothing here says whether an account exists.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+    /**
+     * Finish a connection for `username`: the identity the provider vouched
+     * for, or null. Only a flow started to connect that same account counts.
+     */
+    verifyIdentity(credentials: AuthVerifyCredentials, username: string): Promise<OidcIdentity | null>;
+    /**
+     * The verified identity a refused sign-in brought that no account has
+     * connected, or null; read before `consumeToken` (#1743 slice 3).
+     */
+    unconnectedIdentity(state: string): OidcIdentity | null;
+    /** Spend the flow's state; true only for the caller that did (#1021). */
+    consumeToken(state: string): boolean;
+    /**
+     * The state, the browser, the code exchange and the ID token, checked in
+     * that order. `connectFor` is the account a connection is for, or null for
+     * a sign-in; a flow of the other kind is refused.
+     */
+    private redeem;
+    /** Exchange the code for the ID token. No access or refresh token is kept. */
+    private exchange;
+    /** The client secret for one code exchange: the shared one, or a freshly signed JWT (Apple). */
+    private clientSecret;
+    /** Signature, issuer, audience and expiry; the keys are fetched again once if none matches (rotation). */
+    private verifyIdToken;
+    private keySet;
+    /** The issuer's discovery document, cached; its `issuer` must be the configured one (OIDC Discovery §4.3). */
+    private discover;
+    private getJson;
+    private sweep;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * OidcBearerAuthProvider — accepts access tokens issued by this instance's own
+ * OpenID Connect provider on ngdpbase's API (#1576).
+ *
+ * An app that a person allowed through /oidc holds a token for the audience
+ * `<base-url>/api`. That token is a delegation from the person, like an agent
+ * token: its scopes are permission names and ride on `viaToken`, so the PDP
+ * ceiling and the edge gate (#1173) bound it exactly as they bound an agent
+ * token, and authority stays the person's, resolved live. Unlike an agent
+ * token it also carries how the person signed in, so roles above that level
+ * step down (`aal`), as in a web session.
+ *
+ * Verification is OidcManager's, in process; this provider only adapts it.
+ */
+import type { AuthProvider, AuthResult, AuthVerifyCredentials, ViaToken } from './BaseAuthProvider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+export interface OidcBearerAuthResult extends AuthResult {
+    viaToken: ViaToken;
+    aal: 1 | 2 | 3;
+}
+export declare class OidcBearerAuthProvider implements AuthProvider {
+    private readonly engine;
+    readonly id = "oidc-bearer";
+    readonly displayName = "OpenID Connect access token";
+    /** Marks this provider as usable by the bearer middleware. */
+    readonly acceptsBearer = true;
+    constructor(engine: WikiEngine);
+    verify(credentials: AuthVerifyCredentials): Promise<OidcBearerAuthResult | null>;
+}
+export default OidcBearerAuthProvider;

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

@@ -0,0 +1,58 @@
+import type { PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON } from '@simplewebauthn/server';
+import type { AuthProvider, AuthResult, AuthVerifyCredentials, FactorDescription } from './BaseAuthProvider.js';
+import type { CredentialRecord } from './BaseCredentialsProvider.js';
+/** What a passkey row's `secret` holds. Public material only. */
+export interface PasskeySecret {
+    publicKey: string;
+    counter: number;
+    /** As the authenticator reported them; v14 types transports as plain strings. */
+    transports?: string[];
+    deviceType: 'singleDevice' | 'multiDevice';
+    backedUp: boolean;
+}
+export interface PasskeyRelyingParty {
+    /** The host of base-url — the relying-party id. */
+    rpID: string;
+    /** The origin of base-url — what the browser must report. */
+    origin: string;
+    /** Shown by the authenticator when creating a passkey. */
+    rpName: string;
+}
+/** The store access AuthManager grants: find by credential id, record a use. */
+export interface PasskeyStoreAccess {
+    find(credentialId: string): CredentialRecord | null;
+    used(id: string, at: string, secret: string): Promise<void>;
+}
+/** The base-url origin, its host, and whether WebAuthn may run there (https, or localhost). */
+export declare function relyingPartyFrom(baseUrl: string, rpName: string): PasskeyRelyingParty | null;
+export declare class PasskeyAuthProvider implements AuthProvider {
+    private readonly rp;
+    private readonly store;
+    readonly id = "passkey";
+    readonly 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.
+     */
+    readonly factor: FactorDescription;
+    constructor(rp: PasskeyRelyingParty, store: PasskeyStoreAccess);
+    /** The relying party passkeys are tied to — for the admin page and the enrol screen. */
+    relyingParty(): PasskeyRelyingParty;
+    /** Options for enrolling a passkey; `existing` keeps one authenticator from enrolling twice. */
+    registrationOptions(username: string, displayName: string, existing: readonly CredentialRecord[]): Promise<PublicKeyCredentialCreationOptionsJSON>;
+    /** Verify an enrolment; returns what the credentials store keeps, or null when it does not verify. */
+    verifyRegistration(response: RegistrationResponseJSON, expectedChallenge: string): Promise<{
+        subject: string;
+        secret: string;
+    } | null>;
+    /** Options for signing in: no username asked, any passkey for this host may answer. */
+    authenticationOptions(): Promise<PublicKeyCredentialRequestOptionsJSON>;
+    /**
+     * 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.
+     */
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 type { AuthProvider, AuthVerifyCredentials, AuthResult, FactorDescription } from './BaseAuthProvider.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+export declare class PasswordAuthProvider implements AuthProvider {
+    private engine;
+    readonly id = "password";
+    readonly displayName = "Username & Password";
+    /** Something you know (#1523). */
+    readonly factor: FactorDescription;
+    constructor(engine: WikiEngine);
+    verify(credentials: AuthVerifyCredentials): Promise<AuthResult | null>;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The application database as one SQLite file, encrypted with SQLCipher when a
+ * key is given (#1536). Ported from yourPHR (yourphr#617).
+ *
+ * Opened and migrated in the constructor, so every provider built over the
+ * handle sees a finished schema. WAL mode with `synchronous = FULL`: a
+ * committed transaction is on the device before the call returns. WAL needs
+ * shared memory, which network filesystems do not provide, so the file's
+ * location is checked first (`refuseNetworkFilesystem`).
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+import BaseDatabaseProvider from './BaseDatabaseProvider.js';
+import type { ProviderDurability } from './BaseProvider.js';
+import { type Migration, type MigrationReport } from './sqliteMigrations.js';
+export type SqliteHandle = InstanceType<typeof Database>;
+/** The lock wait when none is configured: the driver's own default, stated (#1710). */
+export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle> {
+    private readonly file;
+    protected providerName: string;
+    protected providerDescription: string;
+    private readonly db;
+    private closed;
+    private readonly encrypted;
+    /** What the ledger did at open: the ids applied now, and how many were already there. */
+    readonly migrations: MigrationReport;
+    /**
+     * @param file   the database file; created when absent
+     * @param key    the SQLCipher key; '' opens the file unencrypted
+     * @param ledger the migrations, strictly ascending by id
+     * @param ledgerTable where applied ids are recorded; an add-on's database names its own (#13)
+     * @param options.busyTimeoutMs how long a statement waits for a lock another connection holds
+     *   (`ngdpbase.database.busy-timeout-ms`, #1710) before failing with SQLITE_BUSY
+     */
+    constructor(file: string, key: string, ledger: Migration[], ledgerTable?: string, options?: {
+        busyTimeoutMs?: number;
+    });
+    /**
+     * Run a further migration ledger on this connection, recorded in its own
+     * table: an add-on that depends on the add-on owning this database brings
+     * its own tables (ngdp-accounting-addons#13). Same rules as the ledger run at
+     * open: once, in order, transactional, and a newer schema is refused.
+     */
+    migrate(ledger: Migration[], ledgerTable: string): MigrationReport;
+    get handle(): SqliteHandle;
+    storage(): {
+        location: string;
+        sizeBytes: number;
+        encrypted: boolean;
+    };
+    integrityOk(): boolean;
+    getDurability(): ProviderDurability;
+    close(): void;
+}
+export default SqliteDatabaseProvider;

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -0,0 +1,90 @@
+/**
+ * The application database as one SQLite file, encrypted with SQLCipher when a
+ * key is given (#1536). Ported from yourPHR (yourphr#617).
+ *
+ * Opened and migrated in the constructor, so every provider built over the
+ * handle sees a finished schema. WAL mode with `synchronous = FULL`: a
+ * committed transaction is on the device before the call returns. WAL needs
+ * shared memory, which network filesystems do not provide, so the file's
+ * location is checked first (`refuseNetworkFilesystem`).
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+import { existsSync, statSync } from 'node:fs';
+import BaseDatabaseProvider from './BaseDatabaseProvider.js';
+import { runMigrations } from './sqliteMigrations.js';
+import { refuseNetworkFilesystem } from './sqliteLocation.js';
+/** The lock wait when none is configured: the driver's own default, stated (#1710). */
+export const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+class SqliteDatabaseProvider extends BaseDatabaseProvider {
+    file;
+    providerName = 'SqliteDatabaseProvider';
+    providerDescription = 'SQLite application database, SQLCipher-encrypted when a key is set';
+    db;
+    closed = false;
+    encrypted;
+    /** What the ledger did at open: the ids applied now, and how many were already there. */
+    migrations;
+    /**
+     * @param file   the database file; created when absent
+     * @param key    the SQLCipher key; '' opens the file unencrypted
+     * @param ledger the migrations, strictly ascending by id
+     * @param ledgerTable where applied ids are recorded; an add-on's database names its own (#13)
+     * @param options.busyTimeoutMs how long a statement waits for a lock another connection holds
+     *   (`ngdpbase.database.busy-timeout-ms`, #1710) before failing with SQLITE_BUSY
+     */
+    constructor(file, key, ledger, ledgerTable = 'schema_migrations', options = {}) {
+        super();
+        this.file = file;
+        refuseNetworkFilesystem(file);
+        this.db = new Database(file, { timeout: options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS });
+        this.encrypted = key !== '';
+        try {
+            if (this.encrypted) {
+                this.db.pragma("cipher='sqlcipher'");
+                this.db.pragma(`key='${key.replace(/'/g, "''")}'`);
+            }
+            // The first read: a wrong key fails here, before anything is written.
+            this.db.pragma('journal_mode = WAL');
+            this.db.pragma('synchronous = FULL');
+            this.migrations = runMigrations(this.db, ledger, ledgerTable);
+        }
+        catch (err) {
+            this.db.close();
+            throw err;
+        }
+    }
+    /**
+     * Run a further migration ledger on this connection, recorded in its own
+     * table: an add-on that depends on the add-on owning this database brings
+     * its own tables (ngdp-accounting-addons#13). Same rules as the ledger run at
+     * open: once, in order, transactional, and a newer schema is refused.
+     */
+    migrate(ledger, ledgerTable) {
+        return runMigrations(this.db, ledger, ledgerTable);
+    }
+    get handle() {
+        return this.db;
+    }
+    storage() {
+        return { location: this.file, sizeBytes: existsSync(this.file) ? statSync(this.file).size : 0, encrypted: this.encrypted };
+    }
+    integrityOk() {
+        try {
+            const rows = this.db.pragma('quick_check');
+            return String(rows[0]?.quick_check ?? '').toLowerCase() === 'ok';
+        }
+        catch {
+            return false;
+        }
+    }
+    getDurability() {
+        return { bufferedForMs: 0, bufferedRecords: 0, fsync: true };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+    }
+}
+export default SqliteDatabaseProvider;