@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/providers/BaseCredentialsProvider.js

@@ -0,0 +1,21 @@
+/**
+ * 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 const CREDENTIALS_KEY_ENV = 'NGDPBASE_CREDENTIALS_KEY';
+export const CREDENTIAL_KINDS = ['passkey', 'totp', 'email', 'sms', 'device', 'identity', 'proxy', 'invitation'];
+class BaseCredentialsProvider extends BaseProvider {
+}
+export default BaseCredentialsProvider;

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

@@ -68,8 +68,12 @@ export interface ScanResult {
     skippedTruncated?: boolean;
     /** Number of indexed items with no usable capture date (EXIF/QuickTime) — they sort by file mtime (#807) */
     noCaptureDate?: number;
+    /** Paths of the first items counted in `noCaptureDate`, capped; the count stays exact (#2191) */
+    noCaptureDateFiles?: string[];
     /** Number of indexed items with a partial (year-only / year+month) EXIF date, defaulted to Jan 1 (#808) */
     partialCaptureDate?: number;
+    /** Paths of the first items counted in `partialCaptureDate`, capped; the count stays exact (#2191) */
+    partialCaptureDateFiles?: string[];
     /** Number of stale index entries pruned because their file vanished from a scanned folder (#867) */
     removed?: number;
     /** Total elapsed time in milliseconds */

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

@@ -225,6 +225,14 @@ declare abstract class BasePageProvider extends BaseProvider {
      * @returns {string|null} Canonical page title or null
      */
     abstract findPage(identifier: string): string | null;
+    /**
+     * The uuid of the page that holds `name` as its title, or as its slug (#2140)
+     * @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
+     */
+    abstract uuidHoldingName(field: 'title' | 'slug', name: string, ctx: ActorContext): string | null;
     /**
      * Get a page by its UUID
      * @param {string} uuid - Page UUID

package/lib/src/providers/CloudflareAccessAuthProvider.js

@@ -0,0 +1,160 @@
+/**
+ * CloudflareAccessAuthProvider — JWT-based trust of Cloudflare Access (#649).
+ *
+ * Cloudflare Access is a zero-trust gateway: it authenticates users at the
+ * edge (against your IdP) and forwards a signed JWT to the origin in the
+ * `Cf-Access-Jwt-Assertion` header. This provider verifies that JWT and
+ * coordinates the identity to a local User record.
+ *
+ * Design decisions (per #649 operator-confirmed 2026-05-25):
+ *  - Q1 — User coordination by **email** (`identity.email` from the JWT).
+ *  - Q2 — Unknown user → **JIT-provision** with default-role (overridable
+ *    per CF group via `group-map`).
+ *  - Q3 — CF `identity.groups[]` → ngdpbase roles via **config-map**.
+ *
+ * Cloudflare-Access-specific — not a generalised federated-IdP abstraction.
+ *
+ * Wire-up: this provider is invoked by the request-time middleware in
+ * `src/app.ts` (header → verify → JIT-or-lookup → `req.session.username`).
+ * It does NOT participate in the explicit /login flow; routes call AuthManager
+ * with `providerId='cloudflare-access'` only from the middleware path.
+ *
+ * Token verification uses `jose.createRemoteJWKSet` against
+ * `https://<team-domain>/cdn-cgi/access/certs` — keys are fetched on demand
+ * and cached + rotated by jose internally.
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { jobContextFromRequestWithReason } from '../context/JobContext.js';
+import { systemPrincipalOf } from '../context/bootActions.js';
+import logger from '../utils/logger.js';
+import { emailDomain } from '../utils/emailForLog.js';
+export class CloudflareAccessAuthProvider {
+    id = 'cloudflare-access';
+    displayName = 'Cloudflare Access';
+    /** An identity provider, as Google: AAL1 with no `amr` of its own (#1523). */
+    factor = { amr: [], aal: 1, primary: true };
+    engine;
+    config;
+    jwks;
+    issuer;
+    /**
+     * @param jwksOverride optional pre-built JWKS getter for tests; production
+     *   omits this and uses `createRemoteJWKSet` against the team-domain certs
+     *   endpoint.
+     */
+    constructor(engine, config, jwksOverride) {
+        this.engine = engine;
+        this.config = config;
+        this.issuer = `https://${config.teamDomain}`;
+        this.jwks = jwksOverride
+            ?? createRemoteJWKSet(new URL(`${this.issuer}/cdn-cgi/access/certs`));
+    }
+    /**
+     * Verify the Cloudflare Access JWT and resolve (or provision) the local user.
+     * `credentials.token` is the raw JWT lifted from the `Cf-Access-Jwt-Assertion`
+     * header by the request-time middleware.
+     */
+    async verify(credentials) {
+        const token = credentials.token;
+        if (!token) {
+            return null;
+        }
+        let verified;
+        try {
+            verified = await jwtVerify(token, this.jwks, {
+                issuer: this.issuer,
+                audience: this.config.applicationAud
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[CloudflareAccessAuthProvider] JWT verification failed: ${message}`);
+            return null;
+        }
+        const payload = verified.payload;
+        const email = payload.email?.toLowerCase();
+        if (!email) {
+            logger.warn('[CloudflareAccessAuthProvider] JWT had no email claim');
+            return null;
+        }
+        return this.resolveOrProvision(email, payload);
+    }
+    async resolveOrProvision(email, payload) {
+        const userManager = this.engine.getManager('UserManager');
+        if (!userManager) {
+            logger.error('[CloudflareAccessAuthProvider] UserManager unavailable');
+            return null;
+        }
+        // Email-keyed lookup (Q1=a).
+        // #2073: an email several accounts share is refused, never guessed between
+        // and never given a new account: a gateway's header cannot ask which.
+        const holders = await userManager.getUsersByEmail(email);
+        if (holders.length > 1) {
+            logger.warn(`[CloudflareAccessAuthProvider] ${holders.length} accounts share an address at ${emailDomain(email)}; refused, since a gateway sign-in cannot ask which (#2073)`);
+            return null;
+        }
+        const existing = holders[0];
+        if (existing) {
+            logger.info(`[CloudflareAccessAuthProvider] Existing user matched: ${existing.username}`);
+            return { username: existing.username };
+        }
+        // JIT-provision (Q2=i). Username derived from local-part of email; if
+        // already taken (e.g. existing local-only user with same handle but
+        // different email), append a numeric suffix.
+        const desiredUsername = email.split('@')[0];
+        const username = await this.deriveUniqueUsername(userManager, desiredUsername);
+        const displayName = payload.identity?.name || username;
+        const roles = this.mapGroupsToRoles(payload.identity?.groups ?? []);
+        try {
+            const created = await userManager.createUser({
+                username,
+                email,
+                displayName,
+                // Federated users have no local password — mirrors GoogleOIDC's pattern
+                // (src/providers/GoogleOIDCProvider.ts:215). isExternal=true blocks
+                // local password reset; isActive=true allows immediate login.
+                password: '',
+                roles,
+                isExternal: true,
+                isActive: true
+            }, jobContextFromRequestWithReason({ username: systemPrincipalOf(this.engine) }, 'provisioned by cloudflare-access')); // #1204: provisioned, not registered; #1179: the system principal acts, the reason names the provider
+            logger.info(`[CloudflareAccessAuthProvider] JIT-provisioned user: ${username} (an address at ${emailDomain(email)}) with roles=[${roles.join(', ')}]`);
+            return { username: created.username }; // #1882: the account as stored
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`[CloudflareAccessAuthProvider] JIT provision failed for ${username}:`, message);
+            return null;
+        }
+    }
+    /**
+     * Map CF identity.groups[] to ngdpbase role names. Groups without an
+     * entry in config.groupMap are dropped silently. Result always contains
+     * config.defaultRole — even with no group hits, user gets the default.
+     */
+    mapGroupsToRoles(groups) {
+        const out = new Set([this.config.defaultRole]);
+        for (const g of groups) {
+            const mapped = this.config.groupMap[g];
+            if (mapped)
+                out.add(mapped);
+        }
+        return Array.from(out);
+    }
+    async deriveUniqueUsername(userManager, desired) {
+        const getUser = userManager.getUser;
+        if (typeof getUser !== 'function')
+            return desired;
+        let candidate = desired;
+        let suffix = 1;
+        // Cap at a sane number — defensive only; collisions are rare in practice.
+        while (suffix < 100) {
+            const existing = await getUser.call(userManager, candidate);
+            if (!existing)
+                return candidate;
+            candidate = `${desired}${suffix}`;
+            suffix++;
+        }
+        return `${desired}-${Date.now()}`;
+    }
+}

package/lib/src/providers/FileCredentialsProvider.js

@@ -0,0 +1,188 @@
+/**
+ * The credentials store as one JSON file beside the user store (#1524),
+ * `${FAST_STORAGE}/users/credentials.json` by default.
+ *
+ * - Written owner-only (`0600`) through the atomic save, so the file is never
+ *   readable by other local accounts, not even mid-write (#1560).
+ * - Every row carries `sig`: HMAC-SHA-256 over its fields in a fixed order,
+ *   keyed by `NGDPBASE_CREDENTIALS_KEY`. On load a row whose signature is
+ *   missing or wrong is reported and can never sign anyone in; it is kept in
+ *   quarantine and written back unchanged (#1633), so a lost key costs no
+ *   data. `scripts/retrust-credentials.ts` re-signs them on purpose.
+ * - Nothing here is a password hash. Public keys, (when TOTP is built, #421, encrypted seeds) and token
+ *   hashes are low value to a reader; a writer is what signing stops.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import fs from 'fs-extra';
+import path from 'node:path';
+import BaseCredentialsProvider, { CREDENTIAL_KINDS } from './BaseCredentialsProvider.js';
+import { writeFileAtomic } from '../utils/atomicWrite.js';
+import { secureExistingSecretFile } from '../utils/secretFileMode.js';
+import logger from '../utils/logger.js';
+/** The signed fields, in a fixed order, so a signature never depends on key order in the file. */
+function canonical(r) {
+    return JSON.stringify([r.id, r.username, r.kind, r.subject, r.secret, r.label, r.createdAt, r.lastUsedAt ?? null]);
+}
+function isRecord(r) {
+    const o = r;
+    return typeof o === 'object' && o !== null &&
+        ['id', 'username', 'subject', 'secret', 'label', 'createdAt'].every(k => typeof o[k] === 'string') &&
+        CREDENTIAL_KINDS.includes(o.kind) &&
+        (o.lastUsedAt === undefined || typeof o.lastUsedAt === 'string');
+}
+class FileCredentialsProvider extends BaseCredentialsProvider {
+    file;
+    key;
+    providerName = 'FileCredentialsProvider';
+    providerDescription = 'Signed JSON credentials store beside the user store';
+    rows = new Map();
+    /** #1633: rows that failed verification, exactly as read, written back unchanged. */
+    quarantine = [];
+    /**
+     * @param file the store; created on first write
+     * @param key  `NGDPBASE_CREDENTIALS_KEY`; refused when empty
+     */
+    constructor(file, key) {
+        super();
+        this.file = file;
+        this.key = key;
+        if (!key)
+            throw new Error('The credentials store needs NGDPBASE_CREDENTIALS_KEY (#1524)');
+    }
+    sign(r) {
+        return createHmac('sha256', this.key).update(canonical(r)).digest('base64');
+    }
+    verifies(r, sig) {
+        const expected = Buffer.from(this.sign(r));
+        const given = Buffer.from(sig);
+        return expected.length === given.length && timingSafeEqual(expected, given);
+    }
+    async initialize(onRejected) {
+        this.rows.clear();
+        this.quarantine = [];
+        if (!(await fs.pathExists(this.file)))
+            return;
+        const tightened = secureExistingSecretFile(this.file); // #1560
+        if (tightened)
+            logger.warn(tightened);
+        const parsed = JSON.parse(await fs.readFile(this.file, 'utf8'));
+        const rejected = [];
+        for (const raw of Array.isArray(parsed.rows) ? parsed.rows : []) {
+            const { sig, ...fields } = raw;
+            let reason = null;
+            if (!isRecord(fields))
+                reason = 'malformed';
+            else if (typeof sig !== 'string' || sig === '')
+                reason = 'unsigned';
+            else if (!this.verifies(fields, sig))
+                reason = 'bad-signature';
+            if (reason) {
+                const entry = { row: fields, reason };
+                rejected.push(entry);
+                this.quarantine.push({ raw: raw, rejected: entry });
+            }
+            else {
+                this.rows.set(fields.id, fields);
+            }
+        }
+        if (rejected.length > 0)
+            onRejected(rejected);
+    }
+    list(username) {
+        return [...this.rows.values()]
+            .filter(r => r.username === username)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    listKind(kind) {
+        return [...this.rows.values()]
+            .filter(r => r.kind === kind)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    get(id) {
+        return this.rows.get(id) ?? null;
+    }
+    async add(record) {
+        if (!isRecord(record))
+            throw new Error('Not a credential record (#1524)');
+        if (this.rows.has(record.id))
+            throw new Error(`Credential ${record.id} already exists`);
+        for (const r of this.rows.values()) {
+            if (r.kind === record.kind && r.subject === record.subject) {
+                throw new Error(`A ${record.kind} credential with that subject is already enrolled`);
+            }
+        }
+        this.rows.set(record.id, { ...record });
+        await this.save();
+    }
+    async remove(id) {
+        if (!this.rows.delete(id))
+            return false;
+        await this.save();
+        return true;
+    }
+    findBySubject(kind, subject) {
+        for (const r of this.rows.values())
+            if (r.kind === kind && r.subject === subject)
+                return r;
+        return null;
+    }
+    async touch(id, at, secret) {
+        const r = this.rows.get(id);
+        if (!r)
+            return;
+        r.lastUsedAt = at;
+        if (secret !== undefined)
+            r.secret = secret;
+        await this.save();
+    }
+    async relabel(id, label) {
+        const r = this.rows.get(id);
+        if (!r)
+            return false;
+        r.label = label;
+        await this.save();
+        return true;
+    }
+    location() {
+        return this.file;
+    }
+    quarantined() {
+        return this.quarantine.map(q => q.rejected);
+    }
+    async retrustQuarantined() {
+        const trusted = [];
+        const kept = [];
+        for (const q of this.quarantine) {
+            const { sig: _sig, ...fields } = q.raw;
+            const clash = isRecord(fields) && (this.rows.has(fields.id) ||
+                [...this.rows.values()].some(r => r.kind === fields.kind && r.subject === fields.subject));
+            if (!isRecord(fields) || clash) {
+                kept.push(q);
+                continue;
+            }
+            this.rows.set(fields.id, { ...fields });
+            trusted.push({ ...fields });
+        }
+        this.quarantine = kept;
+        if (trusted.length > 0)
+            await this.save();
+        return trusted;
+    }
+    getDurability() {
+        return { bufferedForMs: 0, bufferedRecords: 0, fsync: true };
+    }
+    async save() {
+        const out = {
+            version: 1,
+            rows: [
+                ...[...this.rows.values()].map(r => ({ ...r, sig: this.sign(r) })),
+                // #1633: quarantined rows go back exactly as they were read — never
+                // re-signed here, never dropped — until an operator re-trusts them.
+                ...this.quarantine.map(q => q.raw)
+            ]
+        };
+        await fs.ensureDir(path.dirname(this.file), { mode: 0o700 });
+        await writeFileAtomic(this.file, JSON.stringify(out, null, 2), 'utf8', { fsync: true, mode: 0o600 });
+    }
+}
+export default FileCredentialsProvider;

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

@@ -221,6 +221,12 @@ declare class FileSystemMediaProvider extends BaseMediaProvider {
      * Patterns ending with `/` are directory-only; all others match both files and dirs.
      */
     private matchesIgnorePattern;
+    /**
+     * Add a file to a capture-date list until CAPTURE_DATE_LIST_CAP (#2191).
+     * The path is relative to the media folder it was found under, so the
+     * notice and its email do not disclose the server's storage layout.
+     */
+    private listCaptureDateFile;
     /**
      * Process a single media file: stat, EXIF read, index update.
      */