feedkeeper 0.0.0-stage → 0.23.0

package/server/dist/auth/securityRoutes.js

@@ -0,0 +1,249 @@
+import { Router } from "express";
+import rateLimit from "express-rate-limit";
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
+import { db } from "../db/index.js";
+import { config } from "../config.js";
+import { findUserById } from "./users.js";
+import { verifyPassword } from "./password.js";
+import { requireSessionOrDevice } from "./middleware.js";
+import { discardSecurityChallenge, hasTotp, issueSecurityChallenge, newRecoveryCodes, readSecurityChallenge, revokeSecuritySessions, seal, securityAccount, securityBinding, securityVersion, totpFor, verifySecondFactor } from "./security.js";
+export function createSecurityRouter(options) {
+    const router = Router();
+    const origin = new URL(options.publicUrl ?? config.publicUrl).origin;
+    const rpID = new URL(origin).hostname;
+    const passkeysEnabled = origin.startsWith("https:") || rpID === "localhost" || rpID === "127.0.0.1";
+    const channel = options.channel ?? "web";
+    const binding = (req) => securityBinding(req, `${channel}-login`);
+    const managementBinding = (req) => securityBinding(req, `${channel}-management`);
+    const invalid = (res) => { res.status(400).json({ error: "invalid_or_expired_code" }); };
+    const limiter = rateLimit({ windowMs: 5 * 60_000, limit: 120, standardHeaders: true, legacyHeaders: false, message: { error: "too_many_requests" } });
+    router.use((_req, res, next) => { res.setHeader("Cache-Control", "private, no-store"); next(); });
+    router.use((req, res, next) => {
+        if (req.method !== "GET" && (req.headers["sec-fetch-site"] === "cross-site" || (req.headers.origin && req.headers.origin !== origin))) {
+            res.status(403).json({ error: "invalid_origin" });
+            return;
+        }
+        next();
+    });
+    router.use(limiter);
+    const management = [options.authenticate ?? requireSessionOrDevice, (req, res, next) => {
+            if (req.tokenScope === "read" || (req.tokenKind && req.tokenKind !== "device")) {
+                res.status(403).json({ error: "forbidden" });
+                return;
+            }
+            next();
+        }];
+    const proof = (req) => {
+        const row = readSecurityChallenge(req.body?.reauthToken, "reauth", managementBinding(req), true);
+        return row?.user_id === req.user.id;
+    };
+    const issueProof = (req, res) => res.json({ reauthToken: issueSecurityChallenge("reauth", req.user.id, managementBinding(req), {}) });
+    const list = (userId) => db.prepare("SELECT id, name, created_at, last_used_at FROM passkeys WHERE user_id = ? ORDER BY created_at").all(userId);
+    router.get("/config", (_req, res) => res.json({ passkeys: passkeysEnabled, totp: true }));
+    router.get("/pending", (req, res) => res.json({ challengeId: req.session?.pendingMfa ?? null }));
+    router.post("/mfa", (req, res) => {
+        const row = readSecurityChallenge(req.body?.challengeId, "mfa", binding(req));
+        if (!row?.user_id || !verifySecondFactor(row.user_id, req.body?.code)) {
+            invalid(res);
+            return;
+        }
+        discardSecurityChallenge(req.body.challengeId);
+        options.completeLogin(req, res, row.user_id, JSON.parse(row.payload));
+    });
+    router.post("/passkeys/options", async (req, res) => {
+        if (!passkeysEnabled) {
+            res.status(503).json({ error: "https_required" });
+            return;
+        }
+        const context = options.loginContext?.(req) ?? (channel === "web" ? { remember: req.body?.remember === true } : null);
+        if (context === null) {
+            res.status(400).json({ error: "invalid_input" });
+            return;
+        }
+        const publicKey = await generateAuthenticationOptions({ rpID, userVerification: "required" });
+        const challengeId = issueSecurityChallenge("passkey-login", null, binding(req), { challenge: publicKey.challenge, context });
+        res.json({ challengeId, publicKey });
+    });
+    async function assertion(req, purpose, keyBinding) {
+        const row = readSecurityChallenge(req.body?.challengeId, purpose, keyBinding, true);
+        if (!row)
+            return null;
+        const credential = req.body?.credential;
+        if (typeof credential?.id !== "string")
+            return null;
+        const saved = db.prepare("SELECT * FROM passkeys WHERE id = ?").get(credential.id);
+        if (!saved || (row.user_id && saved.user_id !== row.user_id))
+            return null;
+        const handle = credential.response?.userHandle;
+        // Discoverable login must identify the account. A scoped reauthentication may omit the handle.
+        if ((!row.user_id && !handle) || (handle != null && handle !== securityAccount(saved.user_id).user_handle))
+            return null;
+        const version = securityVersion(saved.user_id);
+        try {
+            const result = await verifyAuthenticationResponse({ response: credential, expectedChallenge: JSON.parse(row.payload).challenge, expectedOrigin: origin, expectedRPID: rpID, requireUserVerification: true,
+                credential: { id: saved.id, publicKey: new Uint8Array(saved.public_key), counter: saved.counter, transports: JSON.parse(saved.transports) } });
+            if (!result.verified || version !== securityVersion(saved.user_id))
+                return null;
+            // Avoid accepting two assertions against the same older counter after asynchronous verification.
+            const updated = db.prepare("UPDATE passkeys SET counter = ?, last_used_at = ? WHERE id = ? AND counter = ?").run(result.authenticationInfo.newCounter, new Date().toISOString(), saved.id, saved.counter);
+            if (!updated.changes)
+                return null;
+            return { userId: saved.user_id, payload: JSON.parse(row.payload) };
+        }
+        catch {
+            return null;
+        }
+    }
+    router.post("/passkeys/verify", async (req, res) => {
+        const result = await assertion(req, "passkey-login", binding(req));
+        if (!result) {
+            invalid(res);
+            return;
+        }
+        options.completeLogin(req, res, result.userId, result.payload.context);
+    });
+    router.get("/", ...management, (req, res) => res.json({ totpEnabled: hasTotp(req.user.id), passkeysEnabled, emailReauthEnabled: options.emailReauthEnabled?.(req.user.id) === true, passkeys: list(req.user.id), recoveryCodesRemaining: db.prepare("SELECT COUNT(*) AS n FROM recovery_codes WHERE user_id = ?").get(req.user.id).n }));
+    router.post("/reauth", ...management, (req, res) => {
+        const user = findUserById(req.user.id);
+        if (typeof req.body?.password !== "string" || req.body.password.length > 1024 || !verifyPassword(req.body.password, user.password_hash) || (hasTotp(user.id) && !verifySecondFactor(user.id, req.body.code))) {
+            res.status(401).json({ error: "invalid_credentials" });
+            return;
+        }
+        issueProof(req, res);
+    });
+    router.post("/reauth/passkey/options", ...management, async (req, res) => {
+        if (!passkeysEnabled) {
+            res.status(503).json({ error: "https_required" });
+            return;
+        }
+        const publicKey = await generateAuthenticationOptions({ rpID, userVerification: "required", allowCredentials: list(req.user.id).map(key => ({ id: key.id })) });
+        res.json({ challengeId: issueSecurityChallenge("passkey-reauth", req.user.id, managementBinding(req), { challenge: publicKey.challenge }), publicKey });
+    });
+    router.post("/reauth/passkey/verify", ...management, async (req, res) => {
+        const result = await assertion(req, "passkey-reauth", managementBinding(req));
+        if (!result || result.userId !== req.user.id) {
+            invalid(res);
+            return;
+        }
+        issueProof(req, res);
+    });
+    router.post("/passkeys/register/options", ...management, async (req, res) => {
+        if (!passkeysEnabled) {
+            res.status(503).json({ error: "https_required" });
+            return;
+        }
+        if (!proof(req)) {
+            res.status(401).json({ error: "reauth_required" });
+            return;
+        }
+        const user = findUserById(req.user.id);
+        if (list(user.id).length >= 20) {
+            res.status(400).json({ error: "passkey_limit" });
+            return;
+        }
+        const publicKey = await generateRegistrationOptions({ rpID, rpName: "FeedKeeper", userName: user.email, userDisplayName: user.display_name, userID: Buffer.from(securityAccount(user.id).user_handle, "base64url"), attestationType: "none", excludeCredentials: list(user.id).map(key => ({ id: key.id })), authenticatorSelection: { residentKey: "required", userVerification: "required" } });
+        res.json({ challengeId: issueSecurityChallenge("passkey-register", user.id, managementBinding(req), { challenge: publicKey.challenge }), publicKey });
+    });
+    router.post("/passkeys/register/verify", ...management, async (req, res) => {
+        const row = readSecurityChallenge(req.body?.challengeId, "passkey-register", managementBinding(req), true);
+        if (row?.user_id !== req.user.id || typeof req.body?.name !== "string" || !req.body.name.trim() || req.body.name.length > 100) {
+            invalid(res);
+            return;
+        }
+        try {
+            const result = await verifyRegistrationResponse({ response: req.body.credential, expectedChallenge: JSON.parse(row.payload).challenge, expectedOrigin: origin, expectedRPID: rpID, requireUserVerification: true });
+            if (!result.verified || !result.registrationInfo || row.version !== securityVersion(req.user.id)) {
+                invalid(res);
+                return;
+            }
+            if (list(req.user.id).length >= 20) {
+                res.status(400).json({ error: "passkey_limit" });
+                return;
+            }
+            const key = result.registrationInfo.credential;
+            const transports = key.transports ?? [];
+            db.prepare("INSERT INTO passkeys (id, user_id, public_key, counter, transports, name, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)").run(key.id, req.user.id, Buffer.from(key.publicKey), key.counter, JSON.stringify(transports), req.body.name.trim(), new Date().toISOString());
+            res.status(201).json({ passkeys: list(req.user.id) });
+        }
+        catch {
+            invalid(res);
+        }
+    });
+    router.delete("/passkeys/:id", ...management, (req, res) => {
+        if (!proof(req)) {
+            res.status(401).json({ error: "reauth_required" });
+            return;
+        }
+        // A host may have passwordless accounts: never remove the final usable passkey through this endpoint.
+        if (list(req.user.id).length <= 1 && !(options.canRemoveLastPasskey?.(req.user.id) ?? true)) {
+            res.status(409).json({ error: "last_passkey" });
+            return;
+        }
+        db.prepare("DELETE FROM passkeys WHERE id = ? AND user_id = ?").run(String(req.params.id), req.user.id);
+        res.status(204).end();
+    });
+    router.post("/totp/setup", ...management, (req, res) => {
+        if (!proof(req)) {
+            res.status(401).json({ error: "reauth_required" });
+            return;
+        }
+        if (hasTotp(req.user.id)) {
+            res.status(409).json({ error: "totp_already_enabled" });
+            return;
+        }
+        const totp = totpFor(undefined, req.user.email);
+        res.json({ challengeId: issueSecurityChallenge("totp-setup", req.user.id, managementBinding(req), { secret: seal(totp.secret.base32) }), secret: totp.secret.base32, uri: totp.toString() });
+    });
+    router.post("/totp/confirm", ...management, (req, res) => {
+        const row = readSecurityChallenge(req.body?.challengeId, "totp-setup", managementBinding(req));
+        if (row?.user_id !== req.user.id || typeof req.body?.code !== "string" || !/^\d{6}$/.test(req.body.code) || hasTotp(req.user.id)) {
+            invalid(res);
+            return;
+        }
+        const result = db.transaction(() => {
+            db.prepare("UPDATE account_security SET totp_secret = ?, totp_last_step = -1 WHERE user_id = ?").run(JSON.parse(row.payload).secret, row.user_id);
+            if (!verifySecondFactor(row.user_id, req.body.code)) {
+                db.prepare("UPDATE account_security SET totp_secret = NULL WHERE user_id = ?").run(row.user_id);
+                return null;
+            }
+            const recoveryCodes = newRecoveryCodes(row.user_id);
+            revokeSecuritySessions(row.user_id);
+            // Keep this authenticated browser open so the recovery codes can be saved; other sessions are revoked.
+            if (!req.headers.authorization)
+                req.session.securityVersion = securityVersion(row.user_id);
+            return recoveryCodes;
+        })();
+        if (!result) {
+            invalid(res);
+            return;
+        }
+        res.json({ recoveryCodes: result });
+    });
+    router.post("/totp/disable", ...management, (req, res) => {
+        if (!proof(req)) {
+            res.status(401).json({ error: "reauth_required" });
+            return;
+        }
+        db.transaction(() => {
+            db.prepare("UPDATE account_security SET totp_secret = NULL, totp_last_step = -1 WHERE user_id = ?").run(req.user.id);
+            db.prepare("DELETE FROM recovery_codes WHERE user_id = ?").run(req.user.id);
+            revokeSecuritySessions(req.user.id);
+            if (!req.headers.authorization)
+                req.session.securityVersion = securityVersion(req.user.id);
+        })();
+        res.status(204).end();
+    });
+    router.post("/recovery-codes", ...management, (req, res) => {
+        if (!proof(req)) {
+            res.status(401).json({ error: "reauth_required" });
+            return;
+        }
+        if (!hasTotp(req.user.id)) {
+            res.status(400).json({ error: "totp_required" });
+            return;
+        }
+        res.json({ recoveryCodes: db.transaction(() => newRecoveryCodes(req.user.id))() });
+    });
+    return router;
+}
+//# sourceMappingURL=securityRoutes.js.map

package/server/dist/auth/tokens.js

@@ -0,0 +1,64 @@
+import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
+import { db } from "../db/index.js";
+import { resolveAccessToken } from "../oauth/store.js";
+const TOKEN_PREFIX = "fk_";
+const OAUTH_ACCESS_PREFIX = "fk_oat_";
+function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+// Returns the plaintext token once; only the hash is persisted.
+export function createPersonalAccessToken(userId, name, scope, device) {
+    const secret = randomBytes(32).toString("base64url");
+    const token = `${TOKEN_PREFIX}${device ? "dev_" : ""}${secret}`;
+    const tokenHash = hashToken(token);
+    const tokenPrefix = token.slice(0, 10);
+    const result = db
+        .prepare(`INSERT INTO personal_access_tokens (user_id, name, token_hash, token_prefix, scope, kind, platform, app_version)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(userId, name, tokenHash, tokenPrefix, scope, device ? "device" : "api", device?.platform ?? null, device?.appVersion ?? null);
+    return { id: Number(result.lastInsertRowid), token };
+}
+export function resolveToken(token) {
+    if (!token.startsWith(TOKEN_PREFIX))
+        return null;
+    if (token.startsWith(OAUTH_ACCESS_PREFIX)) {
+        const grant = resolveAccessToken(token);
+        return grant ? { userId: grant.userId, scope: grant.scope, kind: "oauth", tokenId: grant.grantId } : null;
+    }
+    const tokenHash = hashToken(token);
+    const row = db
+        .prepare("SELECT * FROM personal_access_tokens WHERE token_hash = ?")
+        .get(tokenHash);
+    if (!row)
+        return null;
+    // Defense in depth: even though the lookup is by exact hash match, compare
+    // in constant time to avoid timing side channels on the hash comparison.
+    const stored = Buffer.from(row.token_hash, "hex");
+    const provided = Buffer.from(tokenHash, "hex");
+    if (stored.length !== provided.length || !timingSafeEqual(stored, provided)) {
+        return null;
+    }
+    db.prepare("UPDATE personal_access_tokens SET last_used_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?").run(row.id);
+    return { userId: row.user_id, scope: row.scope, kind: row.kind, tokenId: row.id };
+}
+/** Hand-made tokens only; paired devices are listed separately. */
+export function listTokensForUser(userId) {
+    return db
+        .prepare("SELECT * FROM personal_access_tokens WHERE user_id = ? AND kind = 'api' ORDER BY created_at DESC")
+        .all(userId)
+        .map(({ token_hash, ...rest }) => rest);
+}
+export function deleteToken(userId, tokenId) {
+    db.prepare("DELETE FROM personal_access_tokens WHERE id = ? AND user_id = ? AND kind = 'api'").run(tokenId, userId);
+}
+export function listDevicesForUser(userId) {
+    return db
+        .prepare("SELECT * FROM personal_access_tokens WHERE user_id = ? AND kind = 'device' ORDER BY created_at DESC")
+        .all(userId)
+        .map(({ token_hash, ...rest }) => rest);
+}
+/** Revokes a device; its token stops working immediately. Returns whether one was removed. */
+export function deleteDevice(userId, deviceId) {
+    return db.prepare("DELETE FROM personal_access_tokens WHERE id = ? AND user_id = ? AND kind = 'device'").run(deviceId, userId).changes > 0;
+}
+//# sourceMappingURL=tokens.js.map

package/server/dist/auth/users.js

@@ -0,0 +1,54 @@
+import { db } from "../db/index.js";
+import { hashPassword } from "./password.js";
+// Joins only the avatar timestamp; the image itself is loaded on demand.
+const SELECT_USER = `SELECT users.*, user_avatars.updated_at AS avatar_updated_at
+  FROM users LEFT JOIN user_avatars ON user_avatars.user_id = users.id`;
+export function toPublicUser(user) {
+    const { password_hash, ...rest } = user;
+    return rest;
+}
+/** Marks the introduction as seen; it stays marked once it is (the first time counts). */
+export function dismissIntro(userId) {
+    db.prepare("UPDATE users SET intro_dismissed_at = COALESCE(intro_dismissed_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')) WHERE id = ?").run(userId);
+}
+export function findUserByEmail(email) {
+    return db.prepare(`${SELECT_USER} WHERE users.email = ?`).get(email.toLowerCase());
+}
+export function findUserById(id) {
+    return db.prepare(`${SELECT_USER} WHERE users.id = ?`).get(id);
+}
+export function createUser(input) {
+    const result = db
+        .prepare(`INSERT INTO users (email, password_hash, display_name, role)
+       VALUES (?, ?, ?, ?)`)
+        .run(input.email.toLowerCase(), hashPassword(input.password), input.displayName, input.role);
+    return findUserById(Number(result.lastInsertRowid));
+}
+export function updateUserPassword(userId, newPassword) {
+    db.prepare("UPDATE users SET password_hash = ? WHERE id = ?").run(hashPassword(newPassword), userId);
+}
+export function listUsers() {
+    return db
+        .prepare(`${SELECT_USER} ORDER BY users.created_at ASC`)
+        .all()
+        .map(toPublicUser);
+}
+export function updateDisplayName(userId, displayName) {
+    db.prepare("UPDATE users SET display_name = ? WHERE id = ?").run(displayName, userId);
+}
+export function getUserAvatar(userId) {
+    return db
+        .prepare("SELECT mime_type, data FROM user_avatars WHERE user_id = ?")
+        .get(userId);
+}
+export function setUserAvatar(userId, mimeType, data) {
+    db.prepare(`INSERT INTO user_avatars (user_id, mime_type, data) VALUES (?, ?, ?)
+     ON CONFLICT(user_id) DO UPDATE SET
+       mime_type = excluded.mime_type,
+       data = excluded.data,
+       updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`).run(userId, mimeType, data);
+}
+export function deleteUserAvatar(userId) {
+    db.prepare("DELETE FROM user_avatars WHERE user_id = ?").run(userId);
+}
+//# sourceMappingURL=users.js.map

package/server/dist/backup-cli.js

@@ -0,0 +1,101 @@
+import Database from "better-sqlite3";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { config } from "./config.js";
+function assertHealthy(database) {
+    const result = database.pragma("integrity_check", { simple: true });
+    if (result !== "ok")
+        throw new Error(`SQLite integrity check failed: ${String(result)}`);
+}
+// Images of saved articles live next to the backup file as "<backup>.archive".
+const archiveCopyOf = (backupFile) => `${backupFile}.archive`;
+function hasFiles(directory) {
+    return existsSync(directory) && readdirSync(directory).length > 0;
+}
+async function main() {
+    const [action, filename, flag] = process.argv.slice(2);
+    if (!(["backup", "restore"].includes(action) && filename)) {
+        throw new Error("Usage: npm run db:backup -- <destination> | npm run db:restore -- <backup> --force");
+    }
+    const databasePath = resolve(config.databasePath);
+    const filePath = resolve(filename);
+    if (databasePath === filePath)
+        throw new Error("Source and destination must differ");
+    if (action === "backup") {
+        if (!existsSync(databasePath))
+            throw new Error(`Database not found: ${databasePath}`);
+        if (existsSync(filePath))
+            throw new Error(`Backup already exists: ${filePath}`);
+        mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+        process.umask(0o077);
+        const { db } = await import("./db/index.js");
+        try {
+            await db.backup(filePath);
+            const saved = new Database(filePath, { readonly: true, fileMustExist: true });
+            try {
+                assertHealthy(saved);
+            }
+            finally {
+                saved.close();
+            }
+            console.log(`Backup verified: ${filePath}`);
+            const archivePath = resolve(config.archivePath);
+            if (hasFiles(archivePath)) {
+                cpSync(archivePath, archiveCopyOf(filePath), { recursive: true, errorOnExist: true, force: false });
+                console.log(`Archived images copied: ${archiveCopyOf(filePath)}`);
+            }
+        }
+        catch (error) {
+            if (existsSync(filePath))
+                unlinkSync(filePath);
+            rmSync(archiveCopyOf(filePath), { recursive: true, force: true });
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+        return;
+    }
+    if (flag !== "--force")
+        throw new Error("Restore replaces the configured database. Stop FeedKeeper and pass --force.");
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        throw new Error(`Backup file not found: ${filePath}`);
+    // A backup is a WAL-mode database, and SQLite needs to create a -shm file next to a database it opens, even for
+    // reading. The backup may sit where nothing can be created (a single file mounted into a container, a read-only
+    // volume), so it is opened from a copy in the temporary folder.
+    const scratch = mkdtempSync(join(tmpdir(), "feedkeeper-restore-"));
+    const copy = join(scratch, "backup.sqlite");
+    copyFileSync(filePath, copy);
+    const source = new Database(copy, { readonly: true, fileMustExist: true });
+    try {
+        assertHealthy(source);
+        mkdirSync(dirname(databasePath), { recursive: true, mode: 0o700 });
+        process.umask(0o077);
+        await source.backup(databasePath);
+    }
+    finally {
+        source.close();
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    const restored = new Database(databasePath, { readonly: true, fileMustExist: true });
+    try {
+        assertHealthy(restored);
+    }
+    finally {
+        restored.close();
+    }
+    console.log(`Database restored and verified: ${databasePath}`);
+    const archiveBackup = archiveCopyOf(filePath);
+    if (existsSync(archiveBackup)) {
+        const archivePath = resolve(config.archivePath);
+        rmSync(archivePath, { recursive: true, force: true });
+        cpSync(archiveBackup, archivePath, { recursive: true });
+        console.log(`Archived images restored: ${archivePath}`);
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=backup-cli.js.map

package/server/dist/cli.js

@@ -0,0 +1,135 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export const HELP = `FeedKeeper: a self-hosted RSS reader and remote MCP server
+
+Usage:
+  feedkeeper [options]                   Start the server
+  feedkeeper backup <file>               Back up the database (see docs for restore)
+  feedkeeper restore <file> --force      Restore the database from a backup
+
+Options:
+  --port <number>        Port to listen on (default: 3000, or PORT)
+  --public-url <url>     Address people reach this instance at (default: http://localhost:<port>)
+  --data-dir <folder>    Where the database, archive and session secret live
+                         (default: the folder of DATABASE_PATH, otherwise ~/.feedkeeper)
+  -v, --version          Print the version
+  -h, --help             Print this help
+
+A .env file in the current folder is read first; real environment variables win over it.
+Without SESSION_SECRET, one is generated on first start and kept in the data folder.
+All other settings are the environment variables of .env.example in the repository.`;
+export class UsageError extends Error {
+}
+function takeValue(argv, index, flag) {
+    const argument = argv[index];
+    const inline = argument.indexOf("=");
+    if (inline !== -1)
+        return [argument.slice(inline + 1), index];
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("-"))
+        throw new UsageError(`${flag} needs a value`);
+    return [next, index + 1];
+}
+/** Turns the command line into options, or throws a UsageError that says what is wrong. */
+export function parseArgs(argv) {
+    const options = { action: "start", forwarded: [] };
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        const name = argument.split("=")[0];
+        if (argument === "-h" || argument === "--help")
+            return { ...options, action: "help" };
+        if (argument === "-v" || argument === "--version")
+            return { ...options, action: "version" };
+        if (name === "--port") {
+            const [value, next] = takeValue(argv, index, "--port");
+            const port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new UsageError(`--port must be a number from 1 to 65535, got "${value}"`);
+            options.port = port;
+            index = next;
+        }
+        else if (name === "--public-url") {
+            const [value, next] = takeValue(argv, index, "--public-url");
+            let url;
+            try {
+                url = new URL(value);
+            }
+            catch {
+                throw new UsageError(`--public-url must be an address such as https://feeds.example.org, got "${value}"`);
+            }
+            if (url.protocol !== "http:" && url.protocol !== "https:")
+                throw new UsageError(`--public-url must start with http:// or https://, got "${value}"`);
+            options.publicUrl = value.replace(/\/+$/, "");
+            index = next;
+        }
+        else if (name === "--data-dir") {
+            const [value, next] = takeValue(argv, index, "--data-dir");
+            options.dataDir = value;
+            index = next;
+        }
+        else if (options.action === "start" && (argument === "backup" || argument === "restore")) {
+            options.action = argument;
+            options.forwarded.push(argument);
+        }
+        else if (options.action !== "start" && (argument === "--force" || !argument.startsWith("-"))) {
+            // The file name and --force belong to the backup tool; options above are the only ones read here.
+            options.forwarded.push(argument);
+        }
+        else {
+            throw new UsageError(`Unknown ${argument.startsWith("-") ? "option" : "command"} "${argument}"`);
+        }
+    }
+    return options;
+}
+/**
+ * Fills the settings the server needs and an operator should not have to think about on a first start: a data
+ * folder, the database path, the public address that follows the port, and a session secret. Values that are
+ * already set are never replaced, apart from the ones given as options.
+ */
+export function prepareEnvironment(options, env, home = homedir(), persist = options.action === "start") {
+    if (options.port !== undefined)
+        env.PORT = String(options.port);
+    if (options.publicUrl !== undefined)
+        env.PUBLIC_URL = options.publicUrl;
+    if (!env.PUBLIC_URL?.trim())
+        env.PUBLIC_URL = `http://localhost:${env.PORT?.trim() || 3000}`;
+    const configured = env.DATABASE_PATH?.trim();
+    const dataDir = resolve(options.dataDir ?? (env.FEEDKEEPER_DATA_DIR?.trim() || (configured ? dirname(resolve(configured)) : join(home, ".feedkeeper"))));
+    if (!configured || options.dataDir !== undefined)
+        env.DATABASE_PATH = join(dataDir, "feedkeeper.sqlite");
+    if (persist)
+        mkdirSync(dirname(resolve(env.DATABASE_PATH)), { recursive: true, mode: 0o700 });
+    let secretCreated = false;
+    let secretPath = null;
+    if (!env.SESSION_SECRET?.trim()) {
+        secretPath = join(dataDir, "session-secret");
+        const read = () => (existsSync(secretPath) ? readFileSync(secretPath, "utf8").trim() : "");
+        let secret = read();
+        if (!secret && !persist) {
+            // Backup and restore never sign anything, but the configuration insists on a secret: a throwaway one, not stored.
+            env.SESSION_SECRET = randomBytes(32).toString("hex");
+            return { dataDir, secretCreated: false, secretPath: null };
+        }
+        if (!secret) {
+            mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+            try {
+                writeFileSync(secretPath, `${randomBytes(32).toString("hex")}\n`, { flag: "wx", mode: 0o600 });
+                secretCreated = true;
+            }
+            catch (error) {
+                // Another process created it in the meantime: use theirs.
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            secret = read();
+        }
+        if (!secret)
+            throw new Error(`Could not read or create the session secret at ${secretPath}`);
+        env.SESSION_SECRET = secret;
+    }
+    env.NODE_ENV ??= "production";
+    return { dataDir, secretCreated, secretPath };
+}
+//# sourceMappingURL=cli.js.map

package/server/dist/clientAddress.js

@@ -0,0 +1,26 @@
+import { isIP } from "node:net";
+/**
+ * Takes the client address from a header set by a CDN, such as Cloudflare's CF-Connecting-IP.
+ *
+ * Some web servers in front of the app replace X-Forwarded-For with the address of the CDN edge
+ * that connected to them, so `trust proxy` alone finds only that edge. The header is used only when
+ * the request reached the app through the trusted proxies listed in TRUST_PROXY: `req.ip` must itself
+ * be one of them. A client that bypasses the CDN is not trusted, so its own header is ignored.
+ * Hop counts cannot tell a CDN edge from a client, so the header needs a TRUST_PROXY list.
+ */
+export function clientAddressFromHeader(header, trustProxy) {
+    const name = header?.trim().toLowerCase() || null;
+    const enabled = name !== null && Array.isArray(trustProxy);
+    return (req, _res, next) => {
+        if (enabled) {
+            const value = req.headers[name];
+            const address = typeof value === "string" ? value.trim() : "";
+            const trusted = req.app.get("trust proxy fn");
+            if (address && isIP(address) && req.ip && trusted(req.ip, 0)) {
+                Object.defineProperty(req, "ip", { value: address, configurable: true, enumerable: true });
+            }
+        }
+        next();
+    };
+}
+//# sourceMappingURL=clientAddress.js.map