@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,33 @@
+import BaseCredentialsProvider, { type CredentialRecord, type RejectedCredential } from './BaseCredentialsProvider.js';
+import type { ProviderDurability } from './BaseProvider.js';
+declare class FileCredentialsProvider extends BaseCredentialsProvider {
+    private readonly file;
+    private readonly key;
+    protected providerName: string;
+    protected providerDescription: string;
+    private rows;
+    /** #1633: rows that failed verification, exactly as read, written back unchanged. */
+    private quarantine;
+    /**
+     * @param file the store; created on first write
+     * @param key  `NGDPBASE_CREDENTIALS_KEY`; refused when empty
+     */
+    constructor(file: string, key: string);
+    private sign;
+    private verifies;
+    initialize(onRejected: (rejected: RejectedCredential[]) => void): Promise<void>;
+    list(username: string): CredentialRecord[];
+    listKind(kind: CredentialRecord['kind']): CredentialRecord[];
+    get(id: string): CredentialRecord | null;
+    add(record: CredentialRecord): Promise<void>;
+    remove(id: string): Promise<boolean>;
+    findBySubject(kind: CredentialRecord['kind'], subject: string): CredentialRecord | null;
+    touch(id: string, at: string, secret?: string): Promise<void>;
+    relabel(id: string, label: string): Promise<boolean>;
+    location(): string;
+    quarantined(): RejectedCredential[];
+    retrustQuarantined(): Promise<CredentialRecord[]>;
+    getDurability(): ProviderDurability;
+    private save;
+}
+export default FileCredentialsProvider;

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

@@ -0,0 +1,58 @@
+/**
+ * Scheduled-job state as files in FAST_STORAGE (#1714). See `jobState.ts`.
+ *
+ *   <root>/state/<jobId>.json              last slot done, next slot, current run
+ *   <root>/runs/<jobId>.json               run history, newest first, capped
+ *   <root>/checkpoints/<jobId>/<runId>.json
+ *   <root>/locks/<jobId>@<slot>.lock       { owner, expiresAt }
+ *
+ * Every write is atomic and flushed (temp file, fsync, rename), so a crash
+ * mid-write leaves the previous file whole. A lock is created exclusively:
+ * of any servers racing for a slot, the one whose create lands wins. An
+ * expired lock is stolen by renaming it aside and creating a fresh one; the
+ * rename succeeds for one stealer only. Renewal is the holder's job, well
+ * inside the lock's lifetime, so a live holder is never stolen from.
+ *
+ * Refuses to start on NFS or SMB: exclusive create and rename are what the
+ * locks rest on, and network filesystems do not promise them across clients.
+ *
+ * @module providers/FileJobStateProvider
+ */
+import { type StatFsLike } from './sqliteLocation.js';
+import { type JobRunRecord, type JobState, type JobStateLimits, type JobStateProvider } from './jobState.js';
+export interface FileJobStateOptions extends JobStateLimits {
+    /** For tests: the filesystem probe and platform behind the network-filesystem refusal. */
+    statfs?: (p: string) => StatFsLike;
+    platform?: string;
+    /** For tests: the clock. */
+    now?: () => number;
+}
+declare class FileJobStateProvider implements JobStateProvider {
+    private readonly root;
+    readonly backend: "file";
+    private readonly historyLimit;
+    private readonly checkpointMaxBytes;
+    private readonly now;
+    /** One read-modify-write at a time per file, within this process. */
+    private readonly queues;
+    constructor(root: string, options?: FileJobStateOptions);
+    private file;
+    private checkpointFile;
+    private lockFile;
+    private readJson;
+    private write;
+    /** Run `task` after every earlier task on the same file has settled. */
+    private serial;
+    getState(jobId: string): Promise<JobState | null>;
+    putState(state: JobState): Promise<void>;
+    recordRun(jobId: string, run: JobRunRecord): Promise<void>;
+    listRuns(jobId: string): Promise<JobRunRecord[]>;
+    saveCheckpoint(jobId: string, runId: string, data: unknown): Promise<void>;
+    loadCheckpoint(jobId: string, runId: string): Promise<unknown>;
+    clearCheckpoint(jobId: string, runId: string): Promise<void>;
+    private createLock;
+    takeLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    renewLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
+}
+export default FileJobStateProvider;

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

@@ -0,0 +1,43 @@
+/**
+ * FileLoggingProvider - Default logging provider (Issue #169)
+ *
+ * Winston console + rotating-file transports with a timestamped single-line
+ * format. This is the behaviour `src/utils/logger.ts` shipped before #169 —
+ * extracted verbatim behind {@link BaseLoggingProvider} so the storage backend
+ * is swappable without touching call sites. The exported `logger` API is
+ * unchanged.
+ *
+ * @class FileLoggingProvider
+ * @extends BaseLoggingProvider
+ */
+import { Logform } from 'winston';
+import type Transport from 'winston-transport';
+import BaseLoggingProvider, { LoggingProviderConfig, LoggingProviderInfo } from './BaseLoggingProvider.js';
+declare class FileLoggingProvider extends BaseLoggingProvider {
+    /**
+     * Console transport always; rotating-file transport added only when `dir`
+     * is provided (avoids creating ./data/logs before ConfigurationManager
+     * resolves paths — same guard as the pre-#169 logger).
+     */
+    createTransports(config: LoggingProviderConfig): Transport[];
+    createFormat(): Logform.Format;
+    /**
+     * Render whatever a caller passed as the second argument to `logger.*`.
+     *
+     * Winston merges that object onto `info` alongside its own keys, so the
+     * three it owns are excluded, as are its symbol-keyed internals (`level`,
+     * `message`, `splat`) — those are winston's plumbing and putting them in the
+     * line would be noise at best.
+     *
+     * A `stack` is emitted on its own lines because a one-line stack is
+     * unreadable, and reading the stack is the entire reason this exists.
+     *
+     * @param info - The winston info object for one log record
+     * @returns The rendered metadata, or an empty string when there is none
+     */
+    private static renderMeta;
+    getProviderInfo(): LoggingProviderInfo;
+    /** Convert a number or `'<n>[MB|KB|B]'` string to a byte count. */
+    private resolveMaxSize;
+}
+export default FileLoggingProvider;

package/lib/src/providers/FileLoggingProvider.js

@@ -0,0 +1,120 @@
+/**
+ * FileLoggingProvider - Default logging provider (Issue #169)
+ *
+ * Winston console + rotating-file transports with a timestamped single-line
+ * format. This is the behaviour `src/utils/logger.ts` shipped before #169 —
+ * extracted verbatim behind {@link BaseLoggingProvider} so the storage backend
+ * is swappable without touching call sites. The exported `logger` API is
+ * unchanged.
+ *
+ * @class FileLoggingProvider
+ * @extends BaseLoggingProvider
+ */
+import path from 'path';
+import { format, transports } from 'winston';
+import BaseLoggingProvider from './BaseLoggingProvider.js';
+import { redactSecretsFormat } from '../utils/redactSecrets.js';
+import { redactPrivateNamesFormat } from '../utils/redactPrivateNames.js';
+/** Fallback when maxSize is unset or unparseable (1MB) */
+const DEFAULT_MAX_SIZE = 1048576;
+class FileLoggingProvider extends BaseLoggingProvider {
+    /**
+     * Console transport always; rotating-file transport added only when `dir`
+     * is provided (avoids creating ./data/logs before ConfigurationManager
+     * resolves paths — same guard as the pre-#169 logger).
+     */
+    createTransports(config) {
+        const logTransports = [new transports.Console()];
+        if (config.dir) {
+            logTransports.push(new transports.File({
+                filename: path.join(config.dir, 'app.log'),
+                maxsize: this.resolveMaxSize(config.maxSize),
+                maxFiles: config.maxFiles
+            }));
+        }
+        return logTransports;
+    }
+    createFormat() {
+        return format.combine(format.timestamp(), 
+        // #1030: strike configured secrets before anything renders them. Placed
+        // here rather than inside printf so it covers every transport at once,
+        // and before printf because printf is what produces the final line.
+        // The table is empty until WikiEngine fills it — see redactSecrets.ts for
+        // why it cannot be read from config at this point.
+        redactSecretsFormat(), 
+        // #1461: private page titles never reach a log line or /admin/logs.
+        redactPrivateNamesFormat(), format.printf((info) => {
+            const ts = typeof info.timestamp === 'string' ? info.timestamp : JSON.stringify(info.timestamp);
+            const msg = typeof info.message === 'string' ? info.message : JSON.stringify(info.message);
+            // #1141: render the metadata too. This printf used to emit only
+            // timestamp/level/message, so the second argument of every
+            // `logger.error(msg, { error, stack })` call in the codebase was
+            // dropped — a 500 on every missing page logged as the bare line
+            // `[error]: [VIEW] Error viewing page`, with the cause nowhere on
+            // disk. Redaction runs before this (see redactSecretsFormat above),
+            // so what arrives here has already been stripped of secrets.
+            const meta = FileLoggingProvider.renderMeta(info);
+            return meta ? `${ts} [${info.level}]: ${msg} ${meta}` : `${ts} [${info.level}]: ${msg}`;
+        }));
+    }
+    /**
+     * Render whatever a caller passed as the second argument to `logger.*`.
+     *
+     * Winston merges that object onto `info` alongside its own keys, so the
+     * three it owns are excluded, as are its symbol-keyed internals (`level`,
+     * `message`, `splat`) — those are winston's plumbing and putting them in the
+     * line would be noise at best.
+     *
+     * A `stack` is emitted on its own lines because a one-line stack is
+     * unreadable, and reading the stack is the entire reason this exists.
+     *
+     * @param info - The winston info object for one log record
+     * @returns The rendered metadata, or an empty string when there is none
+     */
+    static renderMeta(info) {
+        const own = new Set(['timestamp', 'level', 'message']);
+        const parts = [];
+        let stack;
+        for (const key of Object.keys(info)) {
+            if (own.has(key))
+                continue;
+            const value = info[key];
+            if (value === undefined)
+                continue;
+            if (key === 'stack' && typeof value === 'string') {
+                stack = value;
+                continue;
+            }
+            parts.push(`${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+        }
+        const inline = parts.length > 0 ? parts.join(' ') : '';
+        if (stack) {
+            return inline ? `${inline}\n${stack}` : stack;
+        }
+        return inline;
+    }
+    getProviderInfo() {
+        return {
+            name: 'FileLoggingProvider',
+            version: '1.0.0',
+            description: 'Winston console + rotating-file transports (default)',
+            features: ['console', 'file', 'rotation']
+        };
+    }
+    /** Convert a number or `'<n>[MB|KB|B]'` string to a byte count. */
+    resolveMaxSize(maxSize) {
+        if (typeof maxSize === 'number')
+            return maxSize;
+        if (typeof maxSize === 'string') {
+            const m = maxSize.match(/^(\d+(?:\.\d+)?)\s*(MB|KB|B)?$/i);
+            if (m) {
+                const [, size, unit] = m;
+                const mult = unit?.toUpperCase() === 'MB' ? 1024 * 1024
+                    : unit?.toUpperCase() === 'KB' ? 1024 : 1;
+                return parseFloat(size) * mult;
+            }
+        }
+        return DEFAULT_MAX_SIZE;
+    }
+}
+export default FileLoggingProvider;

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

@@ -0,0 +1,25 @@
+import type { Adapter as OidcAdapter, AdapterPayload as OidcAdapterPayload } from 'oidc-provider';
+export declare class FileOidcAdapterStore {
+    private readonly dir;
+    private readonly now;
+    private readonly models;
+    private readonly queues;
+    constructor(dir: string, now?: () => number);
+    /** Make the directory owner-only. Returns a warning when the filesystem ignores modes. */
+    prepare(): string | null;
+    /** The factory node-oidc-provider calls once per model. */
+    adapterFactory(): (name: string) => OidcAdapter;
+    adapter(name: string): OidcAdapter;
+    /** Live rows of one model whose payload matches, for the manager's own sweeps (sign-out, grants). */
+    listLive(name: string): Promise<OidcAdapterPayload[]>;
+    /** Delete every row of one model whose payload matches; returns how many went. For sign-out (#1572). */
+    destroyWhere(name: string, match: (payload: OidcAdapterPayload) => boolean): Promise<number>;
+    /** Wait for every pending write; used at shutdown. */
+    flush(): Promise<void>;
+    private live;
+    private findBy;
+    private file;
+    private rows;
+    private persist;
+}
+export default FileOidcAdapterStore;