feedkeeper 0.0.0-stage → 0.23.1

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

package/server/dist/config.js

@@ -0,0 +1,51 @@
+import { config as loadEnv } from "dotenv";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readPollSettings } from "./feeds/pollSettings.js";
+import { parseTrustProxy } from "./trustProxy.js";
+import { readImageCacheSettings } from "./feeds/imageCacheSettings.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Loads the repo-root .env regardless of the process's current working
+// directory, so `npm run dev`/`start` behave the same from anywhere.
+// `quiet: true` suppresses dotenv's own console output (including its
+// unrelated third-party promo "tips"), which has no place in server logs.
+loadEnv({ path: join(__dirname, "../../.env"), quiet: true });
+function required(name, fallback) {
+    const value = process.env[name] ?? fallback;
+    if (value === undefined) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+export const config = {
+    imageCache: readImageCacheSettings(),
+    polling: readPollSettings(),
+    port: Number(process.env.PORT ?? 3000),
+    publicUrl: required("PUBLIC_URL", "http://localhost:3000"),
+    databasePath: required("DATABASE_PATH", "./data/feedkeeper.sqlite"),
+    // Images of saved articles live outside the database so it stays small.
+    archivePath: process.env.ARCHIVE_PATH ?? join(dirname(process.env.DATABASE_PATH ?? "./data/feedkeeper.sqlite"), "archive"),
+    sessionSecret: required("SESSION_SECRET"),
+    allowSignup: process.env.ALLOW_SIGNUP === "true",
+    trustProxy: parseTrustProxy(process.env.TRUST_PROXY),
+    clientIpHeader: process.env.CLIENT_IP_HEADER?.trim() || null,
+    minPollIntervalMinutes: Number(process.env.MIN_POLL_INTERVAL_MINUTES ?? 5),
+    retentionReadDays: Number(process.env.RETENTION_READ_DAYS ?? 30),
+    retentionMaxDays: Number(process.env.RETENTION_MAX_DAYS ?? 90),
+    retentionMaxItemsPerFeed: Number(process.env.RETENTION_MAX_ITEMS_PER_FEED ?? 1000),
+    autoCleanupEnabled: process.env.AUTO_CLEANUP_ENABLED !== "false",
+    // Optional: only these hosts may register OAuth redirect URIs (comma-separated). Loopback addresses are always allowed.
+    oauthAllowedRedirectHosts: (process.env.OAUTH_ALLOWED_REDIRECT_HOSTS ?? "")
+        .split(",")
+        .map((host) => host.trim().toLowerCase())
+        .filter(Boolean),
+    showGithubLink: process.env.SHOW_GITHUB_LINK !== "false",
+    githubUrl: process.env.GITHUB_URL ?? "https://github.com/visualfusion/feedkeeper",
+};
+if (!config.sessionSecret.trim()) {
+    throw new Error("SESSION_SECRET must not be empty");
+}
+if (config.sessionSecret.trim().length < 32) {
+    console.warn("[config] SESSION_SECRET is shorter than 32 characters; use a long random secret for new installations");
+}
+//# sourceMappingURL=config.js.map

package/server/dist/db/index.js

@@ -0,0 +1,40 @@
+import Database from "better-sqlite3";
+import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "../config.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATIONS_DIR = join(__dirname, "migrations");
+mkdirSync(dirname(config.databasePath), { recursive: true });
+export const db = new Database(config.databasePath);
+db.pragma("journal_mode = WAL");
+db.pragma("foreign_keys = ON");
+function ensureMigrationsTable() {
+    db.exec(`CREATE TABLE IF NOT EXISTS _migrations (
+      name TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    )`);
+}
+export function runMigrations() {
+    ensureMigrationsTable();
+    const applied = new Set(db.prepare("SELECT name FROM _migrations").all().map((row) => row.name));
+    const files = readdirSync(MIGRATIONS_DIR)
+        .filter((file) => file.endsWith(".sql"))
+        .sort();
+    for (const file of files) {
+        if (applied.has(file))
+            continue;
+        const sql = readFileSync(join(MIGRATIONS_DIR, file), "utf8");
+        const applyMigration = db.transaction(() => {
+            db.exec(sql);
+            db.prepare("INSERT INTO _migrations (name) VALUES (?)").run(file);
+        });
+        applyMigration();
+        console.log(`[db] applied migration ${file}`);
+    }
+}
+export function hasAnyUser() {
+    const row = db.prepare("SELECT COUNT(*) AS count FROM users").get();
+    return row.count > 0;
+}
+//# sourceMappingURL=index.js.map

package/server/dist/db/migrations/0001_init.sql

@@ -0,0 +1,70 @@
+-- Initial schema.
+-- Feeds are shared across users so the same source URL is only ever fetched
+-- once; per-user state (subscription label, read status) lives separately.
+
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('admin', 'user')) DEFAULT 'user',
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE TABLE personal_access_tokens (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL UNIQUE,
+  token_prefix TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  last_used_at TEXT
+);
+
+CREATE INDEX idx_pat_user ON personal_access_tokens(user_id);
+
+CREATE TABLE feeds (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  url TEXT NOT NULL UNIQUE,
+  title TEXT,
+  site_url TEXT,
+  poll_interval_minutes INTEGER NOT NULL DEFAULT 15,
+  last_polled_at TEXT,
+  last_error TEXT,
+  etag TEXT,
+  last_modified TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE TABLE subscriptions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  feed_id INTEGER NOT NULL REFERENCES feeds(id) ON DELETE CASCADE,
+  label TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE (user_id, feed_id)
+);
+
+CREATE INDEX idx_subscriptions_user ON subscriptions(user_id);
+CREATE INDEX idx_subscriptions_feed ON subscriptions(feed_id);
+
+CREATE TABLE items (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  feed_id INTEGER NOT NULL REFERENCES feeds(id) ON DELETE CASCADE,
+  guid TEXT NOT NULL,
+  title TEXT,
+  link TEXT,
+  content_snippet TEXT,
+  published_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE (feed_id, guid)
+);
+
+CREATE INDEX idx_items_feed ON items(feed_id, published_at DESC);
+
+CREATE TABLE item_reads (
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  item_id INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+  read_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (user_id, item_id)
+);

package/server/dist/db/migrations/0002_feed_health.sql

@@ -0,0 +1,5 @@
+ALTER TABLE feeds ADD COLUMN last_success_at TEXT;
+ALTER TABLE feeds ADD COLUMN consecutive_errors INTEGER NOT NULL DEFAULT 0;
+
+UPDATE feeds SET last_success_at = last_polled_at WHERE last_error IS NULL AND last_polled_at IS NOT NULL;
+UPDATE feeds SET consecutive_errors = 1 WHERE last_error IS NOT NULL;

package/server/dist/db/migrations/0003_retention.sql

@@ -0,0 +1,13 @@
+-- Migration 0003: System settings for database retention and housekeeping
+
+CREATE TABLE IF NOT EXISTS system_settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+INSERT OR IGNORE INTO system_settings (key, value) VALUES
+  ('retention_read_days', '30'),
+  ('retention_max_days', '90'),
+  ('retention_max_items_per_feed', '1000'),
+  ('auto_cleanup_enabled', 'true');

package/server/dist/db/migrations/0004_bookmarks_and_filters.sql

@@ -0,0 +1,20 @@
+-- Migration 0004: Bookmarks (Saved Items) and User Muted Keywords
+
+CREATE TABLE IF NOT EXISTS item_bookmarks (
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  item_id INTEGER NOT NULL REFERENCES items(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (user_id, item_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_bookmarks_user ON item_bookmarks(user_id);
+
+CREATE TABLE IF NOT EXISTS user_muted_keywords (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  keyword TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE (user_id, keyword)
+);
+
+CREATE INDEX IF NOT EXISTS idx_muted_user ON user_muted_keywords(user_id);

package/server/dist/db/migrations/0005_folders.sql

@@ -0,0 +1,15 @@
+-- Migration 0005: Feed Folders / Categories
+
+CREATE TABLE IF NOT EXISTS folders (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE (user_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_folders_user ON folders(user_id);
+
+ALTER TABLE subscriptions ADD COLUMN folder_id INTEGER REFERENCES folders(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_subscriptions_folder ON subscriptions(folder_id);

package/server/dist/db/migrations/0006_feed_position.sql

@@ -0,0 +1,5 @@
+-- Migration 0006: Custom Feed Ordering (position)
+
+ALTER TABLE subscriptions ADD COLUMN position INTEGER NOT NULL DEFAULT 0;
+
+CREATE INDEX IF NOT EXISTS idx_subscriptions_user_pos ON subscriptions(user_id, position);

package/server/dist/db/migrations/0007_item_image_url.sql

@@ -0,0 +1,2 @@
+-- Migration 0007: Store image URL for feed items
+ALTER TABLE items ADD COLUMN image_url TEXT;

package/server/dist/db/migrations/0008_item_content_html.sql

@@ -0,0 +1,2 @@
+-- Migration 0008: Store full content HTML for feed items
+ALTER TABLE items ADD COLUMN content_html TEXT;

package/server/dist/db/migrations/0009_item_full_content_html.sql

@@ -0,0 +1 @@
+ALTER TABLE items ADD COLUMN full_content_html TEXT;

package/server/dist/db/migrations/0010_token_scope.sql

@@ -0,0 +1,3 @@
+-- Existing tokens keep their original write access. New tokens can be read-only.
+ALTER TABLE personal_access_tokens
+  ADD COLUMN scope TEXT NOT NULL DEFAULT 'write' CHECK (scope IN ('read', 'write'));

package/server/dist/db/migrations/0011_user_avatars.sql

@@ -0,0 +1,8 @@
+-- Profile photos live in their own table so user lookups on every request
+-- never load image data, and backups keep covering a single SQLite file.
+CREATE TABLE user_avatars (
+  user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  mime_type TEXT NOT NULL CHECK (mime_type IN ('image/jpeg', 'image/png', 'image/webp')),
+  data BLOB NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);

package/server/dist/db/migrations/0012_full_text_settings.sql

@@ -0,0 +1,5 @@
+-- Per-subscription choice whether the reader may fetch full articles, and a
+-- per-feed memory of sites that answer full-text requests with a consent wall.
+ALTER TABLE subscriptions ADD COLUMN full_text_mode TEXT NOT NULL DEFAULT 'auto' CHECK (full_text_mode IN ('auto', 'never'));
+ALTER TABLE feeds ADD COLUMN full_text_blocks INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE feeds ADD COLUMN full_text_blocked_at TEXT;

package/server/dist/db/migrations/0013_feed_icons.sql

@@ -0,0 +1,4 @@
+-- Icon declared by the feed's website, so the browser does not rely on a
+-- guessed /favicon.ico that may be missing or blank.
+ALTER TABLE feeds ADD COLUMN icon_url TEXT;
+ALTER TABLE feeds ADD COLUMN icon_checked_at TEXT;